acbridge 0.0.1 → 1.0.1

package/package.json

@@ -1,8 +1,36 @@
 {
   "name": "acbridge",
-  "version": "0.0.1",
-  "description": "AC Bridge CLI — name reserved. The real package ships from https://ac-bridge.com",
-  "homepage": "https://ac-bridge.com",
+  "version": "1.0.1",
+  "description": "Control AC Bridge from any terminal: sign in, run the bridge, and drive smart-home devices and Profiles.",
   "license": "UNLICENSED",
-  "files": []
+  "author": "AC BRIDGE LIMITED",
+  "homepage": "https://ac-bridge.com",
+  "bugs": {
+    "email": "support@ac-bridge.com"
+  },
+  "keywords": [
+    "ac-bridge",
+    "smart-home",
+    "home-automation",
+    "claude-code",
+    "codex"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "acbridge": "dist/acbridge.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/acbridge.mjs",
+    "plugin",
+    "hub/dist/hub.cjs"
+  ],
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  }
 }

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "bridge",
+  "owner": {
+    "name": "AC BRIDGE LIMITED"
+  },
+  "metadata": {
+    "description": "Voice-bridge channels for Claude Code — drive a session by voice through Alexa.",
+    "version": "0.2.0"
+  },
+  "plugins": [
+    {
+      "name": "alexa",
+      "source": "./plugins/alexa",
+      "description": "Alexa voice-bridge channel: inject prompts, read replies back, and approve permission prompts by voice."
+    }
+  ]
+}

package/plugin/README.md

@@ -0,0 +1,223 @@
+# plugin/ — the AC Bridge Claude Code plugin
+
+A **Claude Code plugin marketplace** named `bridge` whose single `alexa` plugin is *how the channel
+MCP server actually reaches Claude Code*. It bundles the channel (`../channel/`) as an MCP stdio
+server plus two hooks — a **PreToolUse permission-gate** and a **session-state signal** feed for
+Profiles (see [`../docs/CLAUDE-SIGNALS.md`](../docs/CLAUDE-SIGNALS.md)). Installed once per machine by `acbridge setup`,
+then loaded on every session with `claude --channels plugin:alexa@bridge` — **no `--dangerously-*`
+flag**. This directory is the *packaging* of the `channel/` workspace for that installed-plugin path.
+
+This same `plugins/alexa/scripts/` directory also carries `codex-signal.mjs` — the Codex CLI sibling
+of `signal.mjs` (below). It is **not** registered in this plugin's own `hooks/hooks.json`; Codex CLI
+has its own hooks engine entirely, and `acbridge setup` installs `codex-signal.mjs` directly into
+Codex's `~/.codex/hooks.json` instead (§ below).
+
+## Layout
+
+| Path (under `plugin/`) | Role |
+|------------------------|------|
+| `.claude-plugin/marketplace.json` | Marketplace manifest — declares the marketplace `name: "bridge"` and lists its one plugin, `alexa` (`source: ./plugins/alexa`). |
+| `plugins/alexa/.claude-plugin/plugin.json` | Plugin manifest — `name: "alexa"`, `version 0.1.0`; declares a `channels` capability bound to the `alexa` MCP server. |
+| `plugins/alexa/.mcp.json` | MCP server definition — spawns the channel as `node ${CLAUDE_PLUGIN_ROOT}/dist/channel.mjs`. |
+| `plugins/alexa/hooks/hooks.json` | Registers the `PreToolUse` gate (`→ scripts/gate.mjs`) **plus** the Profiles session-state signals on `SessionStart`/`SessionEnd`/`UserPromptSubmit`/`Stop`/`StopFailure`/`Notification`/`PreToolUse[AskUserQuestion\|ExitPlanMode\|Workflow]`/`PostToolUse`/`PostToolUseFailure`/`SubagentStart`/`SubagentStop`/`PreCompact`/`PostCompact`/`PermissionDenied`/`TaskCompleted` (all `→ scripts/signal.mjs`). |
+| `plugins/alexa/scripts/gate.mjs` | The PreToolUse permission gate (below). |
+| `plugins/alexa/scripts/signal.mjs` | The Profiles session-state signal — maps each lifecycle hook → one of the 28 wire states (+ on every POST: a transcript-tail `context` reading and the raw **mode/model ferry** — the last `permission-mode` record + assistant model id, which the hub diffs into the mode/`modelChanged` states) → `POST /local/session/state`; successful tools → a state-less tick on `POST /local/session/context` (below). |
+| `plugins/alexa/scripts/statusline.mjs` | The statusline TEE — installed as Claude's `statusLine` command by `acbridge` (reversible; chains any existing statusline): POSTs the exact context % + rate-limit % + `model.id`/`display_name` to `/local/session/context` (the `usageHigh` data feed and the freshest `modelChanged` source), then renders. |
+| `plugins/alexa/scripts/codex-signal.mjs` | The Codex CLI sibling of `signal.mjs` (below) — installed into `~/.codex/hooks.json`, **not** this plugin's `hooks/hooks.json`. |
+| `plugins/alexa/dist/channel.mjs` | The bundled channel MCP server — **build artifact** copied from `../channel/` (gitignored; absent until built). |
+
+`${CLAUDE_PLUGIN_ROOT}` is set by Claude Code to the installed plugin's root, so both the `.mcp.json`
+server and the hook resolve relative to wherever the plugin was installed.
+
+## How it's built
+
+`../channel/build.mjs` bundles `channel/src/index.ts` into one self-contained minified ESM file at
+`channel/dist/channel.mjs` (esbuild, `format: esm`, `target: node22`), then **copies that same
+bundle** to `plugin/plugins/alexa/dist/channel.mjs`:
+
+```js
+// channel/build.mjs
+const pluginDist = "../plugin/plugins/alexa/dist";
+copyFileSync("dist/channel.mjs", `${pluginDist}/channel.mjs`);
+```
+
+Both `dist/` outputs are gitignored — regenerate with the channel workspace build. The plugin's
+`.mcp.json` loads exactly this file via `${CLAUDE_PLUGIN_ROOT}/dist/channel.mjs`.
+
+## How it's installed & loaded
+
+**Installed-plugin path (normal).** `acbridge setup` (`cli/src/commands/setup.ts`) does two things,
+once per machine:
+
+1. **Install** the marketplace + plugin — `cli/src/plugin-install.ts` runs
+   `claude plugin marketplace add <repo>/plugin` (the dir is `MARKETPLACE_DIR` in
+   `cli/src/paths.ts`) then `claude plugin install alexa@bridge`. Both are idempotent; the install
+   itself *is* the MCP trust (no per-launch approval prompt).
+2. **Allowlist** the channel in OS managed settings — `../node-core/src/claude-setup/managed-settings.ts`
+   (`cli/src/managed-settings.ts` is a thin adapter over it) writes
+   `/etc/claude-code/managed-settings.json` (Linux/WSL) with `channelsEnabled: true` and
+   `allowedChannelPlugins: [{ marketplace: "bridge", plugin: "alexa" }]`. That write sits **inside
+   `if (voice)`**, so on the shipping **voice-off default nothing is written and setup never asks for
+   sudo** ([`../docs/VOICE-FLAG.md`](../docs/VOICE-FLAG.md)). With voice off the settings are returned
+   **unchanged** — the old auto-withdrawal of previously-injected deny rules was itself removed in
+   2026-07 (v1.0.0 is the first released build, so there are no real upgraders to un-restrict, and
+   silently editing a user's own `permissions.deny` is worse than the vestigial cleanup); tool policy
+   is the user's, not ours to mutate.
+
+Sessions then launch with:
+
+```bash
+claude --channels plugin:alexa@bridge     # cli/src/commands/run.ts (acbridge run)
+```
+
+With voice on, that allowlist is what lets the channel load with **no** dangerous flag — without it
+Claude **refuses** the channel as "not on the approved list". It is mandatory for a voice session, not
+optional.
+
+**Dev path (contrast).** From a from-source checkout you can skip the marketplace entirely and load
+the channel straight from a project/user `.mcp.json` `alexa` entry:
+
+```bash
+claude --dangerously-load-development-channels server:alexa .   # stale form in ../channel/mcp.json
+```
+
+This bypasses the marketplace + managed-settings allowlist and is for local development only; the
+productized launch never uses a `--dangerously-*` flag.
+
+## The permission-gate hook
+
+`scripts/gate.mjs` runs on **every tool call** (`PreToolUse`, matcher `*`) and adds **no tool
+restrictions of its own** (owner decision, 2026-07 security review). It reads the event JSON on stdin
+purely to honour the hook contract — the decision comes from the **session**, not the event:
+
+- **a voice session ⇒ `allow`, unconditionally.** The hands-free flow is the product: a permission
+  prompt mid-session has to be relayed to Alexa as a spoken yes/no for something the user already
+  authorised at install time. Anyone who wants restrictions configures them in their own Claude Code
+  settings — one place, under their control, not split across a plugin they did not write.
+- **every other session ⇒ print nothing = defer** to Claude Code's normal permission flow.
+
+**What that gives up, stated plainly** (the file's own header says it too, so nobody "fixes" this later
+by re-adding rules): a PreToolUse `allow` **short-circuits** Claude Code's permission system, including
+restrictions the user set in their own config. So on a voice session a misheard or prompt-injected
+request can read a secret — `~/.ssh`, `~/.aws`, `.env`, the bridge's own token dir — and the `reply`
+tool is outbound egress, so it can be **spoken back**. An earlier version denied exactly those reads
+plus a set of destructive `Bash` patterns (`rm -rf`, `mkfs`, `dd if=`, fork bombs, force-push); **all of
+those rules are gone**, along with their mirrored managed-settings deny list — and, since 2026-07, the
+auto-withdrawal machinery too (`../node-core/src/claude-setup/managed-settings.ts`: setup neither
+enforces nor removes deny rules; a dev machine still carrying the old ones drops them by hand).
+
+**Why the voice scope is load-bearing:** the plugin stays installed when the voice flag is off — its
+hooks are how agent state reaches the hub, which is what device Profiles react to
+([`../docs/VOICE-FLAG.md`](../docs/VOICE-FLAG.md)). Without this check a voice-off build would be
+overriding the user's permissions everywhere, for a feature it does not ship.
+
+The signal is the **positive** `voice: true` marker every voice writer stamps into the session
+handshake (`$BRIDGE_SECRET_DIR/sessions/<CLAUDE_CODE_SESSION_ID>.json` — written by
+`../channel/src/handshake.ts` and `acbridge run`, and upgraded by the channel at MCP init, before it
+connects, so before any `reply` egress can exist). **Absence is never treated as presence:** no marker,
+no file, no session id, or an unreadable file all **defer**, as does any parse/logic error. Deferring is
+strictly less permissive than allowing, so every uncertain case lands on the user's own configuration.
+
+**Physical-device safety is separate and unaffected.** Security-sensitive smart-home commands (locks,
+garages, valves, cameras) go through the hub's own fail-closed gate — `../hub/src/device-gate.ts` and
+`../relay/src/device-confirm.ts`. Reading a file and unlocking a front door are different risks, and
+only the first one is opened up.
+
+## The session-state signal hook
+
+`scripts/signal.mjs` turns Claude's session lifecycle into a smart-home scene (Profiles — actuated by the
+hub's RulesEngine; the signal catalog is [`../docs/CLAUDE-SIGNALS.md`](../docs/CLAUDE-SIGNALS.md)). One
+dependency-free script, registered against several hooks; it maps
+the firing hook (+ payload) onto **one of the curated/extended session states** and POSTs a lightweight
+`SessionStateRequest` to the local hub's loopback control API (`POST /local/session/state`, the same
+`x-bridge-hub-token` guard as `/local/*`, **no `Origin`**). The hub's RulesEngine fires the bound
+Profile rule **locally** (sub-second, never via the relay); the relay only receives the signal after,
+for read-back.
+
+| state | native hook | note |
+|-------|-------------|------|
+| `started` | `SessionStart` | `source:"compact"` is **silent** (compaction is not a new session) |
+| `resumed` | `SessionStart` (`source:"resume"`) | distinguishes a resume from a cold `started` |
+| `ended` | `SessionEnd` | |
+| `working` | `UserPromptSubmit` | also `PostToolUse[Failure]` on `AskUserQuestion`/`ExitPlanMode` — answering/deciding resumes the turn (a plan **rejection** must not read as an error) |
+| `finished` | `Stop` | fires at the end of **every** turn → the hub debounces per `(session,state)` |
+| `needsInput` | `PreToolUse` (`AskUserQuestion`), `Notification` (`agent_needs_input`/`elicitation_dialog`) | Claude asked YOU a question |
+| `planReady` | `PreToolUse` (`ExitPlanMode`) | a plan awaits your approval |
+| `idle` | `Notification` (`idle_prompt`, or text fallback) | typed `notification_type` preferred; regex fallback for older Claude Code |
+| `needs_permission` | `Notification` (`permission_prompt`, or text fallback) | same typed-first split |
+| `rateLimited` | `Notification` (`rate_limit_warning`), `StopFailure` (`error_type:"rate_limit"`) | usage-limit hit/warning |
+| `error` | `StopFailure` (non-rate-limit), `PostToolUseFailure`, `Notification` (`mcp_server_error`) | plus the legacy best-effort `PostToolUse` `is_error` check |
+| `subagentStart` / `subagentFinished` | `SubagentStart` / `SubagentStop` | |
+| `compacting` / `compactDone` | `PreCompact` / `PostCompact` | `compactDone` re-arms the hub's context latches |
+| `permissionDenied` | `PermissionDenied` | a tool call auto-blocked without asking |
+| `taskCompleted` | `TaskCompleted`, `Notification` (`agent_completed`) | background work finished |
+| `workflowStarted` | `PreToolUse` (`Workflow`) | multi-agent orchestration kicked off (expect a subagent burst) |
+| `contextLow` / `contextCritical` / `usageHigh` | *(hub-synthesized)* | the hub's `SessionContextTracker` fires them at the **profile's slider pct** from the `context` reading attached to every POST (transcript tail), `/local/session/context` ticks (successful tools), and the statusline tee (`scripts/statusline.mjs` — also the only source of rate-limit %). Claude's own `context_low` notification is deliberately unmapped. |
+| `modePlan` / `modeAuto` / `modeBypass` / `modeNormal` | *(hub-synthesized)* | Claude Code has **no hook and no statusline field** for a permission-mode switch, so every POST ferries the transcript's last raw `permissionMode` (`plan` / `auto`\|`acceptEdits` / `bypassPermissions` / `default`) and the hub diffs it per session — **baseline-quiet** (the first observation never fires; a payload `permission_mode`, if Claude Code ever ships one, wins over the transcript). |
+| `modelChanged` | *(hub-synthesized)* | same ferry: the last assistant `message.model` id (+ the statusline's `model.id`/`display_name`) diffed per session; the announcement speaks the display name or a prettified id ("Opus 4.8"). |
+
+**Activation.** `signal.mjs` resolves this run's hub coordinates from (1) the `BRIDGE_*` launch env,
+(2) the per-session handshake file (`SECRET_DIR/sessions/<claude session id>.json`) — written by
+`acbridge run` **or self-written by the channel** on a bare `claude --channels …` — or (3)
+**auto-profiles**: if neither exists but the hub is set up on this machine (a `hub-token` file is
+present) and auto-profiles is on (the default), it **self-derives** the id (`project@machine`) and
+fires. That is what makes lights react on **any** session while the hub daemon runs (voice stays
+flag-gated — only the channel MCP server, which boots solely under `--channels`, does voice). The hub
+only actuates repos **bound** to a Profile, so unbound repos no-op. **No hub configured on this
+machine (no token) ⇒ exit 0, POST nothing.** Off-switch: `BRIDGE_AUTO_PROFILES=0` or `"autoProfiles":
+false` in `config.json`. **Fail-safe:** any parse/IO/network error ⇒ exit 0 (a hook must never block
+Claude); the POST is bounded by a 2 s timeout.
+
+## The Codex session-state signal hook
+
+`scripts/codex-signal.mjs` is the Codex CLI sibling of `signal.mjs` above, for a repo bound to a
+**Codex** profile. It is installed by `acbridge setup` (`node-core/src/codex-setup/hooks.ts`,
+merge-safe/reversible — every foreign hook survives verbatim; off-switch `BRIDGE_CODEX_HOOKS=0` /
+`"autoCodexHooks": false`) directly into **Codex's own** `~/.codex/hooks.json`, registered against 9
+lifecycle events: `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest`, `PreCompact`,
+`PostCompact`, `SubagentStart`, `SubagentStop`, `PostToolUse`. Codex requires a one-time in-TUI
+`/hooks` review before a third-party hook actually runs — `acbridge setup` prints that reminder when
+it changes the file, since it can't bypass the gate.
+
+Unlike `signal.mjs`, Codex's hooks engine posts a single JSON object on stdin per event (no HTTP-hook
+form) and ships `model`/`permission_mode` on **every** event, so the mode/model ferry is a straight
+field read — no transcript walk needed for that part. The context ferry still walks Codex's own
+rollout JSONL the same defensive last-64KB-tail way `signal.mjs` reads Claude's transcript, looking
+for `token_count` rows. It POSTs to the SAME `/local/session/state` / `/local/session/context` hub
+endpoints as `signal.mjs`, with `agent:"codex"` on the body — the hub's `RulesEngine` matches that
+against a compiled rule's `trigger.agent` (a Codex profile's binding lane, `codexBindings`), so a
+repo can react to a Codex session exactly like it reacts to Claude, distinguished by the `~codex` id
+suffix on a self-derived session. `PermissionRequest` is observe-and-abstain: classified for the
+device signal, but this script **never** writes to stdout (Codex reads a permission hook's stdout as
+an approve/deny decision).
+
+Codex has no `SessionEnd`/`Notification`/`StopFailure`/`PermissionDenied`/`TaskCompleted` hooks and
+no rate-limit data; this hook script reaches 17 states directly (the 16 originals plus `error`, from
+an error-shaped tool result on `PostToolUse`), and the adapter/voice surface reaches the rest of the
+23-state codex mask — `CODEX_EVENTS` (`contracts/src/profiles.ts`, 23 of the 28 wire states) — which
+is exactly what the Codex profile editor offers. Same activation
+ladder and fail-safes as `signal.mjs` (BRIDGE_* env → per-session handshake → self-derive when a hub
+is configured on this machine; `BRIDGE_AUTO_PROFILES=0` off-switch; any parse/IO/network error exits
+0) — with one structural difference and one lifecycle gap, both recorded in
+[`../docs/reviews/XPLAT-2026-07-28.md`](../docs/reviews/XPLAT-2026-07-28.md):
+
+- **Local home + fixed port only.** Unlike `signal.mjs`, this script does **not** resolve the
+  WSL↔Windows bridge home: it pins the local `~/.claude-bridge` (`BRIDGE_SECRET_DIR` aside) and the
+  env/config `hubPort` — no `resolveBridgeHome()`, no beacon-port pickup, and no
+  `hooks-last-error.json` breadcrumb on rejection. With the hub on the other side of a WSL↔Windows
+  split (or bound off 8790 without a matching `config.json`), hook-lane Codex Profiles silently no-op.
+- **No `ended`, ever.** No Codex hook can produce the `ended` state (Codex ships no `SessionEnd`),
+  and the hub keys Profile scene revert + arbiter stand-down on `ended` — so a hook-lane Codex session
+  that exits leaves its scene applied and its arbiter claim held on a daemon-kept hub until the next
+  session starts or the hub itself stops. The adapter lane (`acbridge run --agent codex`) does post
+  `ended` and is unaffected.
+
+Full detail: [`../docs/CLAUDE-SIGNALS.md`](../docs/CLAUDE-SIGNALS.md) §7a.
+
+## See also
+
+- `../channel/` — the channel MCP server source this plugin bundles (`dist/channel.mjs`).
+- [`../docs/CLAUDE-SIGNALS.md`](../docs/CLAUDE-SIGNALS.md) — the catalog of Claude session-state signals
+  `signal.mjs` maps onto Profiles (and where the hub's RulesEngine consumes them).
+- `../CLAUDE.md` — the project overview and the Channels-vs-`/rc` architectural constraint.
+- `../docs/DEPLOY.md` — the full go-live runbook (relay → hub/channel → skill → test).

package/plugin/plugins/alexa/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "alexa",
+  "version": "0.4.0",
+  "description": "Alexa voice-bridge channel for Claude Code (inject + reply + permission relay + the full Profiles session-state catalog with context readings).",
+  "author": {
+    "name": "AC BRIDGE LIMITED"
+  },
+  "channels": [
+    {
+      "server": "alexa"
+    }
+  ]
+}

package/plugin/plugins/alexa/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "alexa": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/channel.mjs"]
+    }
+  }
+}