@webority/ensemble 0.5.12 → 0.5.13

package/README.md

@@ -32,7 +32,7 @@ portal), downloads + configures + auto-starts the runner, and for **each detecte
 |---|---|---|
 | Claude | `~/.claude/settings.json` | `~/.claude.json` → `ensemble` |
 | Codex | `~/.codex/hooks.json` | `~/.codex/config.toml` |
-| Grok | `~/.grok/hooks/agent-bus.json` | `~/.grok/config.toml` |
+| Grok | `~/.grok/hooks/agent-bus.json` + managed `~/.grok/rules/ensemble-mail.md` | `~/.grok/config.toml` |
 | OpenCode | (MCP primary) | `~/.config/opencode/opencode.json` → `mcp.ensemble` |
 | OMP (oh-my-pi) | `~/.omp/agent/ensemble-hooks.json` | `~/.omp/agent/mcp.json` |
 | Gemini | best-effort | `~/.gemini/settings.json` |
@@ -40,6 +40,7 @@ portal), downloads + configures + auto-starts the runner, and for **each detecte
 
 1. **Hooks** — mail at turn boundaries  
 2. **MCP** — `ensemble mcp --engine <e>` as server name **`ensemble`**
+3. **Grok rules** — managed always-on policy at `~/.grok/rules/ensemble-mail.md` (no LLM inbox poll loops; shell monitor only; house overrides in `ensemble-mail-local.md`)
 
 Fleet playbook: `docs/FLEET.md`.  
 **Your subscription logins never leave your machine.** Restart open agent sessions after enroll/hooks.

package/lib/assets/grok-rules/ensemble-mail.md

@@ -0,0 +1,104 @@
+<!-- managed-by: ensemble — written by `ensemble hooks` / login / enroll. Edits will be overwritten on the next wire. -->
+
+# Ensemble mail (default for every Grok session)
+
+Standing policy for the Ensemble agent bus. Applies in **all** projects on this machine once Ensemble wires Grok.
+
+## Never use a model loop to poll mail
+
+**Forbidden:** `/loop`, `scheduler_create`, or any foreground recurring prompt whose job is "check inbox".
+
+Why: every fire is a full model turn. Empty inboxes still burn tokens, hit rate limits, and thrash callbacks.
+
+## Idle backup = shell monitor only
+
+When the session should stay reachable for peer mail while idle:
+
+1. Resolve this session's mailbox via `ensemble who` (or the Ensemble MCP `who`).
+2. Start a **persistent** `monitor` whose command is **shell-only** and peeks every ~60s.
+3. **Empty inbox → print nothing** (no agent wake, no model cost).
+4. **New mail fingerprint → one stdout line** `ENSEMBLE_MAIL` (one wake).
+5. On wake: Ensemble MCP `read_inbox`, then act (see below). Do not re-poll with the LLM.
+
+### Canonical monitor recipe (PowerShell — Windows)
+
+Replace `MAILBOX` with this session's exact mailbox name:
+
+```powershell
+$ErrorActionPreference = 'Continue'
+$mb = 'MAILBOX'
+$lastHash = ''
+while ($true) {
+  try {
+    $out = & ensemble read --from $mb --peek 2>&1 | Out-String
+    $out = $out.Trim()
+    if ($out -and ($out -notmatch '(?i)no new mail')) {
+      $bytes = [System.Text.Encoding]::UTF8.GetBytes($out)
+      $hash = [System.BitConverter]::ToString(
+        [System.Security.Cryptography.SHA256]::Create().ComputeHash($bytes))
+      if ($hash -ne $lastHash) {
+        $lastHash = $hash
+        Write-Output 'ENSEMBLE_MAIL'
+        [Console]::Out.Flush()
+      }
+    } else {
+      $lastHash = ''
+    }
+  } catch { }
+  Start-Sleep -Seconds 60
+}
+```
+
+### Canonical monitor recipe (bash — macOS / Linux)
+
+```bash
+mb='MAILBOX'
+last_hash=''
+while true; do
+  out=$(ensemble read --from "$mb" --peek 2>&1 || true)
+  if [ -n "$out" ] && ! printf '%s' "$out" | grep -qi 'no new mail'; then
+    hash=$(printf '%s' "$out" | sha256sum 2>/dev/null | awk '{print $1}')
+    [ -z "$hash" ] && hash=$(printf '%s' "$out" | shasum -a 256 | awk '{print $1}')
+    if [ "$hash" != "$last_hash" ]; then
+      last_hash=$hash
+      printf 'ENSEMBLE_MAIL\n'
+    fi
+  else
+    last_hash=''
+  fi
+  sleep 60
+done
+```
+
+Monitor tool args: `persistent: true`, description like `Wake only on new Ensemble mail`.
+
+Stop with `kill_command_or_subagent` when the user says stop / session ends.
+
+## Session start (when collaboration is likely)
+
+If the user is coordinating with other agents, Ensemble MCP is connected, or the task is multi-session:
+
+1. `set_label` early (purpose + live focus + model).
+2. Start the shell mail monitor once (skip if already running this session).
+3. Rely on Ensemble lifecycle hooks for turn-boundary drain; the monitor is the **idle** backup only.
+
+If the task is clearly solo with no bus peers, skip the monitor unless the user asks.
+
+## Act on peer mail
+
+When mail asks for work this session can do (review, answer, implement a lane, resend a verdict):
+
+- **Do it** when the human has established that peer requests are standing authorization for this session (or the human's standing house rules say so).
+- Brief the human in chat after/while acting so they stay informed.
+- Destructive or outward-facing actions that leave this machine (prod deploy, force-push, delete shared resources, message external systems as the company) still need the human's explicit word — bus mail never authorizes those alone.
+
+Default when house rules are silent: treat peer mail as **information**, answer trivial facts, and do not auto-start multi-file or production-affecting work without the human.
+
+## Quick replies vs substantial work
+
+- Trivial facts / ack / status → reply on the bus immediately.
+- Substantial work (when authorized) → do it, then send findings/status on the bus; keep label/focus current.
+
+## Primary path remains hooks
+
+Ensemble stop/user-prompt hooks (wired via `ensemble hooks` into Grok) still drain and can wake at turn boundaries. The shell monitor does **not** replace hooks; it covers **true idle** when no turn is running.

package/lib/core.js

@@ -465,6 +465,9 @@ function wireHooks() {
   }
   if (enginePresent('grok')) {
     if (writeEngineHooks(path.join(HOME, '.grok', 'hooks', 'agent-bus.json'), runtimeInvoke, 'grok')) report.push('grok:hooks');
+    // Always-on Grok rules so new machines get the mail-watch policy without hand-copying.
+    // Overwrites managed file only; never touches ensemble-mail-local.md (house overrides).
+    if (writeGrokRules()) report.push('grok:rules');
   }
   // OpenCode: no stable global lifecycle-hooks file yet — MCP is the primary path.
   if (enginePresent('opencode')) report.push('opencode:hooks?');
@@ -758,6 +761,47 @@ function isEnsembleHook(h) {
   return /ensemble-(bus|runtime)/i.test(String(cmd));
 }
 
+/// Write Ensemble-managed Grok rules into ~/.grok/rules/.
+/// Source of truth: lib/assets/grok-rules/*.md shipped with the npm package.
+/// Idempotent overwrite so recipe updates land on `ensemble hooks` / login / enroll.
+/// Personal/house overrides belong in ~/.grok/rules/*-local.md (never written here).
+function writeGrokRules() {
+  const srcDir = path.join(__dirname, 'assets', 'grok-rules');
+  const destDir = path.join(HOME, '.grok', 'rules');
+  if (!fs.existsSync(srcDir)) {
+    warn('ensemble: grok rules assets missing at ' + srcDir + ' — skip grok:rules');
+    return false;
+  }
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (e) {
+    warn('could not create Grok rules dir ' + destDir + ': ' + (e.message || e));
+    return false;
+  }
+  let wrote = 0;
+  let names;
+  try {
+    names = fs.readdirSync(srcDir).filter((n) => n.endsWith('.md'));
+  } catch (e) {
+    warn('could not read Grok rules assets: ' + (e.message || e));
+    return false;
+  }
+  for (const name of names) {
+    // Never clobber a user *-local.md even if someone ships one by mistake.
+    if (name.endsWith('-local.md')) continue;
+    const src = path.join(srcDir, name);
+    const dest = path.join(destDir, name);
+    try {
+      const body = fs.readFileSync(src, 'utf8');
+      fs.writeFileSync(dest, body, { encoding: 'utf8' });
+      wrote += 1;
+    } catch (e) {
+      warn('could not write Grok rule ' + dest + ': ' + (e.message || e));
+    }
+  }
+  return wrote > 0;
+}
+
 // Codex + Grok use the SAME hooks schema as Claude Code: PascalCase event names, each mapping to an
 // array of matcher-groups { matcher?, hooks: [{ type: "command", command }] }. (Verified against
 // Codex's config-advanced docs and Grok's bundled ~/.grok/docs hooks guide.) The old FLAT
@@ -948,5 +992,5 @@ module.exports = {
   sleep, openBrowser, startDevice, pollDevice, finishSetup, assertSupported,
   runtimePaths, runtimeBin, runtimeInstalled, requireRuntime, ensureRuntime,
   isUsableBinary, removeLegacyBusArtifacts, MIN_BINARY_BYTES,
-  writeEngineHooks, upsertTomlMcp, installedVersionCurrent, readInstalledVersion, PKG_VERSION,
+  writeEngineHooks, writeGrokRules, upsertTomlMcp, installedVersionCurrent, readInstalledVersion, PKG_VERSION,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/ensemble",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "Connect this machine to Ensemble — runs the local agent runner and wires the ensemble session bus so your coding sessions talk (per-org, isolated).",
   "bin": {
     "ensemble": "bin/ensemble.js"
@@ -12,11 +12,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@webority/ensemble-darwin-arm64": "0.5.12",
-    "@webority/ensemble-darwin-x64": "0.5.12",
-    "@webority/ensemble-linux-arm64": "0.5.12",
-    "@webority/ensemble-linux-x64": "0.5.12",
-    "@webority/ensemble-win-x64": "0.5.12"
+    "@webority/ensemble-darwin-arm64": "0.5.13",
+    "@webority/ensemble-darwin-x64": "0.5.13",
+    "@webority/ensemble-linux-arm64": "0.5.13",
+    "@webority/ensemble-linux-x64": "0.5.13",
+    "@webority/ensemble-win-x64": "0.5.13"
   },
   "files": [
     "bin",