From d06d440086a13e504e54ce326fa875c6e590e308 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 18 Jan 2026 16:20:48 +0000 Subject: [PATCH] docs: clarify macOS node service IPC plan --- CHANGELOG.md | 44 ++++++++++++++++++++---------------- docs/platforms/mac/xpc.md | 17 ++++++++++++++ docs/platforms/macos.md | 16 +++++++++++++ docs/refactor/exec-host.md | 29 +++++++++++++++++------- docs/tools/exec-approvals.md | 17 ++++++++++++++ 5 files changed, 96 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 104f863e4..5f3eab453 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,30 +2,29 @@ Docs: https://docs.clawd.bot -## 2026.1.18-4 +## 2026.1.17-7 ### Changes +- Docs: outline planned macOS node-service IPC and app-owned exec flow. - Memory: add Gemini native embeddings support and auto-select providers when keys are available. (#1167) — thanks @gumadeiras. - Memory: add Gemini batch indexing and atomic reindexing for memory stores. (#1167) — thanks @gumadeiras. +- CLI: show memory status/index across agents with richer source detail. (#1167) — thanks @gumadeiras. +- Docs: refresh FAQ for node approvals, session resets, and memory provider defaults. (#1167) — thanks @gumadeiras. +- Exec approvals: add `clawdbot approvals` CLI for viewing and updating gateway/node allowlists. +- CLI: add `clawdbot service` gateway/node management and a `clawdbot node status` alias. +- Status: show gateway + node service summaries in `clawdbot status` and `status --all`. +- Control UI: add gateway/node target selector for exec approvals. +- Docs: add approvals/service references and refresh node/control UI docs. +- Dependencies: update core + plugin deps (grammy, vitest, openai, Microsoft agents hosting, etc.). - macOS: switch PeekabooBridge integration to the tagged Swift Package Manager release (no submodule). - macOS: stop syncing Peekaboo as a git submodule in postinstall. - Swabble: use the tagged Commander Swift package release. - CLI: add `clawdbot acp client` interactive ACP harness for debugging. - Plugins: route command detection/text chunking helpers through the plugin runtime and drop runtime exports from the SDK. -- CLI: show memory status/index across agents with richer source detail. (#1167) — thanks @gumadeiras. - Memory: add native Gemini embeddings provider for memory search. (#1151) — thanks @gumadeiras. -- Docs: refresh FAQ for node approvals, session resets, and memory provider defaults. (#1167) — thanks @gumadeiras. - -### Fixes -- Tools: clamp bash foreground duration using shared helpers. (#1167) — thanks @gumadeiras. -- Auth profiles: keep auto-pinned preference while allowing rotation on failover; user pins stay locked. (#1138) — thanks @cheeeee. -- macOS: avoid touching launchd in Remote over SSH so quitting the app no longer disables the remote gateway. (#1105) -- Memory: index atomically so failed reindex preserves the previous memory database. (#1151) — thanks @gumadeiras. -- Exec approvals: fix command token parsing for PATH resolution. (#1167) — thanks @gumadeiras. - -## 2026.1.18-3 - -### Changes +- Agents: add local docs path resolution and include docs/mirror/source/community pointers in the system prompt. +- Slack: add HTTP webhook mode via Bolt HTTP receiver for Events API deployments. (#1143) — thanks @jdrhyne. +- Nodes: report core/ui versions in node list + presence; surface both in CLI + macOS UI. - Exec: add host/security/ask routing for gateway + node exec. - Exec: add `/exec` directive for per-session exec defaults (host/security/ask/node). - macOS: migrate exec approvals to `~/.clawdbot/exec-approvals.json` with per-agent allowlists and skill auto-allow toggle. @@ -39,12 +38,20 @@ Docs: https://docs.clawd.bot - Docs: refresh exec/elevated/exec-approvals docs for the new flow. https://docs.clawd.bot/tools/exec-approvals - Docs: add node host CLI + update exec approvals/bridge protocol docs. https://docs.clawd.bot/cli/node - ACP: add experimental ACP support for IDE integrations (`clawdbot acp`). Thanks @visionik. +- Tools: allow `sessions_spawn` to override thinking level for sub-agent runs. +- Channels: unify thread/topic allowlist matching + command/mention gating helpers across core providers. +- Models: add Qwen Portal OAuth provider support. (#1120) — thanks @mukhtharcm. +- Memory: add `--verbose` logging for memory status + batch indexing details. +- Memory: allow parallel OpenAI batch indexing jobs (default concurrency: 2). +- macOS: add per-agent exec approvals with allowlists, skill CLI auto-allow, and settings UI. +- Docs: add exec approvals guide and link from tools index. https://docs.clawd.bot/tools/exec-approvals ### Fixes +- Tools: clamp bash foreground duration using shared helpers. (#1167) — thanks @gumadeiras. - Auth profiles: keep auto-pinned preference while allowing rotation on failover; user pins stay locked. (#1138) — thanks @cheeeee. - Agents: sanitize oversized image payloads before send and surface image-dimension errors. - macOS: avoid touching launchd in Remote over SSH so quitting the app no longer disables the remote gateway. (#1105) -- Memory: index atomically so failed reindex preserves the previous memory database. (#1151) +- Memory: index atomically so failed reindex preserves the previous memory database. (#1151) — thanks @gumadeiras. - Memory: avoid sqlite-vec unique constraint failures when reindexing duplicate chunk ids. (#1151) - Skills: improve remote bin probe logging with node labels + connectivity hints. - Exec approvals: enforce allowlist when ask is off; prefer raw command for node approvals/events. @@ -52,11 +59,10 @@ Docs: https://docs.clawd.bot - Tools: return a companion-app-required message when node exec is requested with no paired node. - Streaming: emit assistant deltas for OpenAI-compatible SSE chunks. (#1147) — thanks @alauppe. - Model fallback: treat timeout aborts as failover while preserving user aborts. (#1137) — thanks @cheeeee. - -## 2026.1.18-2 - -### Fixes - Tests: stabilize plugin SDK resolution and embedded agent timeouts. +- Memory: apply OpenAI batch defaults even without explicit remote config. +- macOS: bundle Textual resources in packaged app builds to avoid code block crashes. (#1006) +- Discord: only emit slow listener warnings after 30s. ## 2026.1.17-6 diff --git a/docs/platforms/mac/xpc.md b/docs/platforms/mac/xpc.md index 348756e23..77b026a96 100644 --- a/docs/platforms/mac/xpc.md +++ b/docs/platforms/mac/xpc.md @@ -7,6 +7,8 @@ read_when: **Current model:** there is **no local control socket** and no `clawdbot-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge. +**Planned model:** add a local Unix socket between the **node service** and the **macOS app**. The app owns `system.run` (UI/TCC context); the node service forwards exec requests over IPC. + ## Goals - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript). - A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation. @@ -17,6 +19,19 @@ read_when: - The app runs the Gateway (local mode) and connects to it as a node. - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`). +### Node service + app IPC (planned) +- A headless node service connects to the Gateway bridge. +- `system.run` requests are forwarded to the macOS app over a local Unix socket. +- The app performs the exec in UI context, prompts if needed, and returns output. + +Diagram (SCI): +``` +Agent -> Gateway -> Bridge -> Node Service (TS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + TCC + system.run) +``` + ### PeekabooBridge (UI automation) - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol. - Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution. @@ -25,6 +40,7 @@ read_when: ### Mach/XPC - Not required for automation; `node.invoke` + PeekabooBridge cover current needs. +- Planned IPC keeps Unix sockets (no XPC helper). ## Operational flows - Restart/rebuild: `SIGN_IDENTITY="Apple Development: ()" scripts/restart-mac.sh` @@ -38,3 +54,4 @@ read_when: - PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development. - All communication remains local-only; no network sockets are exposed. - TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds. +- Planned IPC hardening: socket mode `0600`, token, peer-UID checks, HMAC challenge/response, short TTL. diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index cc873556e..d9ea2a360 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -20,6 +20,10 @@ node. - Optionally hosts **PeekabooBridge** for UI automation. - Installs the global CLI (`clawdbot`) via npm/pnpm on request (bun not recommended for the Gateway runtime). +Planned: +- Run a headless **node service** locally (launchd). +- Keep `system.run` in the app (UI/TCC context), with the node service forwarding via IPC. + ## Local vs remote mode - **Local** (default): the app ensures a local Gateway is running via launchd. @@ -54,6 +58,18 @@ The macOS app presents itself as a node. Common commands: The node reports a `permissions` map so agents can decide what’s allowed. +Planned split: +- Node service advertises the node surface to the Gateway. +- macOS app performs `system.run` in UI context over IPC. + +Diagram (SCI): +``` +Gateway -> Bridge -> Node Service (TS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + TCC + system.run) +``` + ## Exec approvals (system.run) `system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals). diff --git a/docs/refactor/exec-host.md b/docs/refactor/exec-host.md index 8541ce6dc..9cad8c27b 100644 --- a/docs/refactor/exec-host.md +++ b/docs/refactor/exec-host.md @@ -30,6 +30,8 @@ read_when: - **Node identity:** use existing `nodeId`. - **Socket auth:** Unix socket + token (cross-platform); split later if needed. - **Node host state:** `~/.clawdbot/node.json` (node id + pairing token). +- **macOS exec host:** run `system.run` inside the macOS app; node service forwards requests over local IPC. +- **No XPC helper:** stick to Unix socket + token + peer checks. ## Key concepts ### Host @@ -139,19 +141,30 @@ Notes: ## UI integration (macOS app) ### IPC -- Unix socket at `~/.clawdbot/exec-approvals.sock`. -- Runner connects and sends an approval request; UI responds with a decision. -- Token stored in `exec-approvals.json`. +- Unix socket at `~/.clawdbot/exec-approvals.sock` (0600). +- Token stored in `exec-approvals.json` (0600). +- Peer checks: same-UID only. +- Challenge/response: nonce + HMAC(token, request-hash) to prevent replay. +- Short TTL (e.g., 10s) + max payload + rate limit. -### Ask flow -1) Runner receives `system.run` from gateway. -2) If ask required, runner connects to the socket and sends a prompt request. -3) UI shows dialog; returns decision. -4) Runner enforces decision and proceeds. +### Ask flow (macOS app exec host) +1) Node service receives `system.run` from gateway. +2) Node service connects to the local socket and sends the prompt/exec request. +3) App validates peer + token + HMAC + TTL, then shows dialog if needed. +4) App executes the command in UI context and returns output. +5) Node service returns output to gateway. If UI missing: - Apply `askFallback` (`deny|allowlist|full`). +### Diagram (SCI) +``` +Agent -> Gateway -> Bridge -> Node Service (TS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + TCC + system.run) +``` + ## Node identity + binding - Use existing `nodeId` from Bridge pairing. - Binding model: diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index 8f569e425..97a48ae28 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -22,6 +22,10 @@ Exec approvals are enforced locally on the execution host: - **gateway host** → `clawdbot` process on the gateway machine - **node host** → node runner (macOS companion app or headless node host) +Planned macOS split: +- **node service** forwards `system.run` to the **macOS app** over local IPC. +- **macOS app** enforces approvals + executes the command in UI context. + ## Settings and storage Approvals live in a local JSON file on the execution host: @@ -128,6 +132,19 @@ Actions: - **Always allow** → add to allowlist + run - **Deny** → block +### macOS IPC flow (planned) +``` +Gateway -> Bridge -> Node Service (TS) + | IPC (UDS + token + HMAC + TTL) + v + Mac App (UI + approvals + system.run) +``` + +Security notes: +- Unix socket mode `0600`, token stored in `exec-approvals.json`. +- Same-UID peer check. +- Challenge/response (nonce + HMAC token + request hash) + short TTL. + ## System events Exec lifecycle is surfaced as system messages: