omnish 1.6.5 → 2.0.0

package/dist/omnish-cursor/skill/notifications.md

@@ -0,0 +1,155 @@
+# Omnish notifications
+
+Keep terminal noise local; push **curated, readable briefs** to mobile. Default destination: **`*`** (all allowlisted peers). Works on standalone and platform attached gateways.
+
+## Status message format
+
+```bash
+omnish i -c '/sendto * -t <title> -- <brief>'
+```
+
+The brief supports **newlines** — use labeled sections instead of one long pipe-separated line:
+
+```text
+Status: Done
+Chat: <conversation_id>
+Workspace: myapp
+
+You asked:
+Fix notification formatting in cursor hooks
+
+Outcome:
+Updated hook to send multi-line summaries and follow-up messages when content is long.
+
+Tools: 6 action(s)
+```
+
+Message types:
+
+| Type         | When                           |
+| ------------ | ------------------------------ |
+| **Ack**      | Task accepted                  |
+| **Progress** | Major phase change (sparingly) |
+| **Question** | Needs human input              |
+| **Done**     | Finished with outcome          |
+| **Blocked**  | Failure or dependency          |
+
+Rules:
+
+1. Do not stream raw logs to chat.
+2. Lead with key facts (status, chat id, workspace); use newlines between sections.
+3. Summarize in the first message; send **follow-up messages** when the request or outcome needs more context — never chop mid-sentence without a follow-up.
+4. Ask before sending files unless requested.
+5. Include Cursor `conversation_id` when notifying from Cursor agent work.
+
+## Cursor automatic notifications
+
+Install the unified bundle:
+
+```bash
+bash contrib/omnish-cursor/install.sh
+```
+
+Stop hook sends when the agent **changed files** (Write/StrReplace/Delete) or hit an error. Read-only Shell/Grep investigation turns are skipped.
+
+**Dedupe:** same chat + same user ask within `dedupe_minutes` (default 45) → no second ping.
+
+**Follow-ups:** off by default (`send_followups: false`) to avoid mobile floods.
+
+Config `~/.cursor/omnish-notify.json`:
+
+```json
+{
+  "enabled": true,
+  "peer": "*",
+  "min_assistant_chars": 120,
+  "notify_on_error": true,
+  "skip_aborted": true,
+  "include_full_chat_id": true,
+  "summary_max_chars": 300,
+  "followup_max_chars": 1000,
+  "max_followup_messages": 0,
+  "send_followups": false,
+  "dedupe_minutes": 45
+}
+```
+
+| Key                     | Default | Meaning                                             |
+| ----------------------- | ------- | --------------------------------------------------- |
+| `dedupe_minutes`        | `45`    | Suppress repeat pings for same chat + same user ask |
+| `summary_max_chars`     | `300`   | Max length for outcome summary in main message      |
+| `followup_max_chars`    | `1000`  | Max chars per follow-up message (if enabled)        |
+| `max_followup_messages` | `0`     | Extra messages after the main brief                 |
+| `send_followups`        | `false` | Send follow-ups for long requests/outcomes          |
+
+Log: `~/.cursor/hooks/omnish-notify.log`
+
+## Manual and agent-driven sends
+
+Helper script (from omnish repo root):
+
+```bash
+bash scripts/agent-notify.sh "Deploy Done" "Status: Done
+
+Workspace: prod
+Outcome: main branch live"
+```
+
+Uses `OMNISH_PEER_KEY` if set, else `OMNISH_JOB_OWNER_PEER`, else `*`.
+
+Env from `/run` and chat agent daemon:
+
+| Variable                     | Purpose                              |
+| ---------------------------- | ------------------------------------ |
+| `OMNISH_PEER_KEY`            | Initiator peer                       |
+| `OMNISH_NOTIFY_CMD`          | Template with `/sendto peer`         |
+| `OMNISH_COMMUNICATION_BRIEF` | Guidance when `recipesNotifyEnabled` |
+
+For broadcast, omit `OMNISH_PEER_KEY` and use `/sendto *` explicitly.
+
+## Chat-native notifications
+
+**Background jobs** — notify on completion:
+
+```text
+/bg -N -n deploy git pull && npm run build
+```
+
+**Cowork** — conditional notify:
+
+```text
+/cowork set backup when failure
+/cowork set heartbeat when state-change
+```
+
+**Board / specialists** — status via same `/sendto` pattern (see `docs/guides/system-agents-and-run.md`).
+
+## Test notification
+
+```bash
+omnish i -c '/sendto * -t Omnish Test -- Status: Done
+
+Outcome: cursor hook messaging ok'
+```
+
+Requires `omnish run` and non-empty allowlist (or platform token routing).
+
+## Avoid duplicate pings
+
+When Cursor stop hook is installed:
+
+- Do **not** send manual Done for advice-only turns (redeploy, “run npm install on server”, repeated troubleshooting).
+- Do **not** send a second Done if the hook already fired for that turn.
+- Hook skips read-only tools and dedupes same user ask for 45 minutes.
+
+Use Progress/Question/Blocked during work; let the hook handle final Done only when files changed.
+
+## Troubleshooting
+
+| Issue           | Check                                                  |
+| --------------- | ------------------------------------------------------ |
+| No message      | `omnish status`; gateway running; allowlist            |
+| Hook skips      | Log file; turn may be trivial or aborted               |
+| Wrong recipient | `peer` in `omnish-notify.json`                         |
+| Message chopped | Enable `send_followups`; raise `max_followup_messages` |
+| Platform mode   | Token + probe; allowlists on dashboard                 |

package/dist/omnish-cursor/skill/setup-paths.md

@@ -0,0 +1,81 @@
+# Omnish setup paths
+
+Choose exactly one primary path. All paths end with **`omnish run`** on the machine that executes shell commands.
+
+## Platform attached mode (recommended for multi-device)
+
+Messengers (WhatsApp/Telegram) link on the **hosted platform**; each device runs `omnish run` with an account token.
+
+1. Create account on platform dashboard (e.g. `https://tunnel.omnish.dev/dashboard/`).
+2. Link WhatsApp (QR) and/or Telegram (bot token) on the dashboard; save allowlists there.
+3. On each execution host:
+
+```bash
+npm install -g omnish
+omnish platform login --url https://tunnel.omnish.dev --token YOUR_ACCOUNT_TOKEN
+omnish config show platform    # verify URL + token source (masked)
+omnish platform probe          # connectivity check
+omnish run                     # foreground, or: omnish start
+```
+
+4. From allowlisted chat: `!pwd`, `!help`.
+
+**Notes:**
+
+- No local `omnish link` required for WhatsApp when fully platform-attached.
+- Files: outbound `/send` and `omnish i /sendto` use device → platform → messenger; inbound media saves on **your device** paths.
+- Docs: `docs/guides/platform-attached-mode.md`, `docs/guides/platform-reference.md`.
+
+## Standalone WhatsApp
+
+Shell and Baileys session on the same host.
+
+```bash
+npm install -g omnish
+omnish link                    # scan QR (Linked devices)
+omnish allow +15551234567      # E.164 allowlist
+omnish run
+```
+
+Private chats only (no groups). Session under data dir `auth/`. Re-link if session missing in `omnish status`.
+
+## Standalone Telegram
+
+```bash
+npm install -g omnish
+omnish link --tg YOUR_BOT_TOKEN
+# message bot /id to learn your tg id, then:
+omnish allow tg:123456789
+omnish run
+```
+
+Set `gatewayMode` to `telegram` or `both` in config if using both channels.
+
+## Background gateway
+
+```bash
+omnish start                   # background pidfile
+omnish stop
+omnish service install         # boot hints (systemd / LaunchAgent / Task Scheduler)
+```
+
+See `docs/guides/background-and-boot.md`.
+
+## Verify any path
+
+```bash
+omnish status
+omnish security --json         # optional scriptable audit
+```
+
+From chat (allowlisted): `!echo omnish-ok`
+
+## Common failures
+
+| Symptom                            | Fix                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------- |
+| `gateway process: not running`     | `omnish run` or `omnish start`                                         |
+| `session: missing` (standalone WA) | `omnish link`                                                          |
+| `denied` in logs                   | Add sender to allowlist; check LID mapping with `omnish run --verbose` |
+| Platform probe fails               | Check URL/token; `omnish config show platform`                         |
+| `/sendto` no delivery              | Gateway must run; allowlist non-empty for `*`                          |

package/dist/omnish-cursor/uninstall.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Remove Omnish Cursor bundle entries from ~/.cursor (keeps unrelated hooks).
+set -euo pipefail
+
+CURSOR_DIR="${CURSOR_DIR:-$HOME/.cursor}"
+HOOKS_JSON="$CURSOR_DIR/hooks.json"
+
+REMOVE_HOOKS=1
+REMOVE_SKILL=1
+REMOVE_CONFIG=0
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Remove Omnish Cursor integration installed by install.sh.
+
+Options:
+  --hooks-only     Remove hooks + rule + hooks.json entries only
+  --skill-only     Remove ~/.cursor/skills/omnish only
+  --with-config    Also delete ~/.cursor/omnish-notify.json
+  -h, --help       Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hooks-only)
+      REMOVE_HOOKS=1
+      REMOVE_SKILL=0
+      shift
+      ;;
+    --skill-only)
+      REMOVE_HOOKS=0
+      REMOVE_SKILL=1
+      shift
+      ;;
+    --with-config)
+      REMOVE_CONFIG=1
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+OMNISH_COMMANDS=(
+  "./hooks/omnish-session-start.sh"
+  "./hooks/omnish-notify.sh"
+)
+
+if [[ "$REMOVE_HOOKS" -eq 1 && -f "$HOOKS_JSON" ]]; then
+  python3 - "$HOOKS_JSON" "${OMNISH_COMMANDS[@]}" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+hooks_path = Path(sys.argv[1])
+remove_cmds = set(sys.argv[2:])
+data = json.loads(hooks_path.read_text(encoding="utf-8"))
+hooks = data.get("hooks") or {}
+changed = False
+for event, entries in list(hooks.items()):
+    if not isinstance(entries, list):
+        continue
+    filtered = [
+        e for e in entries
+        if not (isinstance(e, dict) and e.get("command") in remove_cmds)
+    ]
+    if len(filtered) != len(entries):
+        changed = True
+        hooks[event] = filtered
+if changed:
+    hooks_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    print(f"updated {hooks_path} (removed omnish hook entries)")
+else
+    print(f"no omnish hook entries in {hooks_path}")
+PY
+fi
+
+if [[ "$REMOVE_HOOKS" -eq 1 ]]; then
+  rm -f \
+    "$CURSOR_DIR/hooks/omnish-notify.sh" \
+    "$CURSOR_DIR/hooks/omnish-notify.py" \
+    "$CURSOR_DIR/hooks/omnish-session-start.sh" \
+    "$CURSOR_DIR/rules/omnish-notify.mdc"
+  echo "removed hook scripts and omnish-notify rule"
+fi
+
+if [[ "$REMOVE_SKILL" -eq 1 ]]; then
+  rm -rf "$CURSOR_DIR/skills/omnish"
+  echo "removed $CURSOR_DIR/skills/omnish"
+fi
+
+if [[ "$REMOVE_CONFIG" -eq 1 ]]; then
+  rm -f "$CURSOR_DIR/omnish-notify.json"
+  echo "removed $CURSOR_DIR/omnish-notify.json"
+fi
+
+echo "Done. Restart Cursor if hooks were removed."