omnish 1.6.6 → 2.0.0

package/dist/omnish-cursor/install.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Install Omnish Cursor bundle: hooks + skill + rule into ~/.cursor
+set -euo pipefail
+
+OMNISH_CURSOR_BUNDLE_URL="${OMNISH_CURSOR_BUNDLE_URL:-https://omnish.dev/downloads/omnish-cursor.tar.gz}"
+_TMP_BUNDLE_DIR=""
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "error: required command not found: $1" >&2
+    exit 1
+  }
+}
+
+cleanup() {
+  if [[ -n "$_TMP_BUNDLE_DIR" && -d "$_TMP_BUNDLE_DIR" ]]; then
+    rm -rf "$_TMP_BUNDLE_DIR"
+  fi
+}
+
+_SCRIPT="${BASH_SOURCE[0]:-}"
+if [[ -n "$_SCRIPT" && -f "$_SCRIPT" ]]; then
+  ROOT="$(cd "$(dirname "$_SCRIPT")" && pwd)"
+else
+  need curl
+  need tar
+  _TMP_BUNDLE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/omnish-cursor.XXXXXX")"
+  trap cleanup EXIT
+  echo "Downloading Omnish Cursor bundle..." >&2
+  curl -fsSL "$OMNISH_CURSOR_BUNDLE_URL" | tar -xzf - -C "$_TMP_BUNDLE_DIR"
+  if [[ ! -d "$_TMP_BUNDLE_DIR/omnish-cursor" ]]; then
+    echo "error: bundle missing omnish-cursor/ top-level directory" >&2
+    exit 1
+  fi
+  ROOT="$_TMP_BUNDLE_DIR/omnish-cursor"
+fi
+
+CURSOR_DIR="${CURSOR_DIR:-$HOME/.cursor}"
+HOOKS_DIR="$CURSOR_DIR/hooks"
+RULES_DIR="$CURSOR_DIR/rules"
+SKILL_DIR="$CURSOR_DIR/skills/omnish"
+
+INSTALL_HOOKS=1
+INSTALL_SKILL=1
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Install Omnish Cursor integration (hooks, skill, rule, config).
+
+Options:
+  --hooks-only   Install only Cursor hooks + rule + notify config
+  --skill-only   Install only the omnish Cursor skill (+ doctor script)
+  -h, --help     Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hooks-only)
+      INSTALL_HOOKS=1
+      INSTALL_SKILL=0
+      shift
+      ;;
+    --skill-only)
+      INSTALL_HOOKS=0
+      INSTALL_SKILL=1
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$INSTALL_HOOKS" -eq 1 ]]; then
+  need python3
+  need omnish
+fi
+
+if [[ "$INSTALL_HOOKS" -eq 1 ]]; then
+  mkdir -p "$HOOKS_DIR" "$RULES_DIR"
+
+  install -m 755 "$ROOT/hooks/omnish-notify.sh" "$HOOKS_DIR/omnish-notify.sh"
+  install -m 755 "$ROOT/hooks/omnish-session-start.sh" "$HOOKS_DIR/omnish-session-start.sh"
+  install -m 644 "$ROOT/hooks/omnish-notify.py" "$HOOKS_DIR/omnish-notify.py"
+  install -m 644 "$ROOT/rules/omnish-notify.mdc" "$RULES_DIR/omnish-notify.mdc"
+
+  if [[ ! -f "$CURSOR_DIR/omnish-notify.json" ]]; then
+    install -m 644 "$ROOT/omnish-notify.json.example" "$CURSOR_DIR/omnish-notify.json"
+    echo "created $CURSOR_DIR/omnish-notify.json"
+  else
+    echo "kept existing $CURSOR_DIR/omnish-notify.json"
+  fi
+
+  python3 - "$CURSOR_DIR/hooks.json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+hooks_path = Path(sys.argv[1])
+desired = {
+    "sessionStart": [{"command": "./hooks/omnish-session-start.sh"}],
+    "stop": [{"command": "./hooks/omnish-notify.sh"}],
+}
+
+if hooks_path.exists():
+    try:
+        data = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        data = {"version": 1, "hooks": {}}
+else:
+    data = {"version": 1, "hooks": {}}
+
+data.setdefault("version", 1)
+hooks = data.setdefault("hooks", {})
+
+for event, entries in desired.items():
+    existing = hooks.get(event) or []
+    commands = {entry.get("command") for entry in existing if isinstance(entry, dict)}
+    merged = list(existing)
+    for entry in entries:
+        if entry["command"] not in commands:
+            merged.append(entry)
+    hooks[event] = merged
+
+hooks_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+print(f"updated {hooks_path}")
+PY
+fi
+
+if [[ "$INSTALL_SKILL" -eq 1 ]]; then
+  mkdir -p "$SKILL_DIR/scripts"
+  install -m 644 "$ROOT/skill/SKILL.md" "$SKILL_DIR/SKILL.md"
+  install -m 644 "$ROOT/skill/setup-paths.md" "$SKILL_DIR/setup-paths.md"
+  install -m 644 "$ROOT/skill/files-and-sharing.md" "$SKILL_DIR/files-and-sharing.md"
+  install -m 644 "$ROOT/skill/notifications.md" "$SKILL_DIR/notifications.md"
+  install -m 755 "$ROOT/scripts/doctor.sh" "$SKILL_DIR/scripts/doctor.sh"
+  echo "installed skill to $SKILL_DIR"
+fi
+
+cat <<EOF
+
+Installed Omnish Cursor bundle.
+
+Next steps:
+  1. Ensure omnish gateway is running: omnish run
+  2. Platform attached: omnish config show platform
+     Local mode: omnish link && omnish allow +E164  (or tg:id)
+  3. Restart Cursor (or reload Hooks in Settings)
+  4. Run: bash $SKILL_DIR/scripts/doctor.sh
+
+Config: $CURSOR_DIR/omnish-notify.json
+Default peer: * (all allowlisted contacts)
+EOF

package/dist/omnish-cursor/omnish-notify.json.example

@@ -0,0 +1,13 @@
+{
+  "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
+}

package/dist/omnish-cursor/rules/omnish-notify.mdc

@@ -0,0 +1,45 @@
+---
+description: Send curated Omnish brief notifications when Cursor agent work completes or needs attention
+alwaysApply: true
+---
+
+# Omnish agent notifications
+
+When this session produces a **new** useful outcome, notify via Omnish with a clear title and structured brief.
+
+## Send when
+
+- Files changed or a fix/feature was **delivered** in the repo
+- Blocked and need a **new** human decision
+- Major milestone on long-running tasks (sparingly — once per phase)
+
+## Skip when (important)
+
+- Pure Q&A, troubleshooting advice, or repeated “redeploy / run this command” with **no new code change**
+- User pastes the **same error again** — do not notify again unless you changed something
+- Trivial lookups or one-line answers
+- Mid-turn exploration with nothing to report yet
+- **Automatic stop hook already sent Done** for this turn — never send a second manual Done
+
+## Do not flood
+
+- One completion → at most **one** Done ping (hook handles it; do not also run `omnish i -c` for Done)
+- Same chat + same user ask + same advice = **no notify**
+- Long error dumps in chat are not “new work” unless you shipped a fix
+
+## Format
+
+```bash
+omnish i -c '/sendto * -t <title> -- <brief>'
+```
+
+Use labeled sections (Status, Chat, Workspace, You asked, Outcome). Include `conversation_id`.
+
+## Types
+
+- **Done** — finished with concise outcome (file changes or verified fix)
+- **Progress** — major phase change only
+- **Question** — needs human decision
+- **Blocked** — failure or dependency
+
+Hook config: `~/.cursor/omnish-notify.json` — defaults skip read-only turns and dedupe repeats for 45 minutes.

package/dist/omnish-cursor/scripts/doctor.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Read-only Omnish + Cursor integration health check.
+set -euo pipefail
+
+CURSOR_DIR="${CURSOR_DIR:-$HOME/.cursor}"
+WARN=0
+
+ok() { printf '  OK   %s\n' "$*"; }
+warn() { printf '  WARN %s\n' "$*"; WARN=1; }
+fail() { printf '  FAIL %s\n' "$*"; }
+
+section() { printf '\n== %s ==\n' "$*"; }
+
+section "Omnish CLI"
+if command -v omnish >/dev/null 2>&1; then
+  ok "omnish on PATH: $(command -v omnish)"
+  omnish --version 2>/dev/null | sed 's/^/       /' || true
+else
+  fail "omnish not found — run: npm install -g omnish"
+  exit 1
+fi
+
+section "Gateway status"
+if omnish status 2>&1 | sed 's/^/  /'; then
+  if omnish status 2>&1 | grep -q 'gateway process: running'; then
+    ok "gateway running"
+  else
+    warn "gateway not running — run: omnish run  (or omnish start)"
+  fi
+else
+  warn "omnish status failed"
+fi
+
+section "Platform config"
+STATUS_OUT="$(omnish status 2>&1 || true)"
+echo "$STATUS_OUT" | sed 's/^/  /'
+if echo "$STATUS_OUT" | grep -q 'platform'; then
+  if echo "$STATUS_OUT" | grep -q 'attached: yes'; then
+    ok "platform attached mode detected (see status above)"
+  elif echo "$STATUS_OUT" | grep -qi 'platformToken\|platform_token'; then
+    ok "platform token configured"
+  else
+    warn "no platform attachment — use standalone link or: omnish platform login --url … --token …"
+  fi
+else
+  warn "could not read platform block from omnish status"
+fi
+
+section "Allowlist hint"
+if omnish status 2>&1 | grep -A2 'Allowed' | grep -q '(none)'; then
+  warn "allowlist empty — add via platform dashboard or: omnish allow +E164 / omnish allow tg:id"
+else
+  ok "allowlist entries detected (see omnish status above)"
+fi
+
+section "Cursor notify config"
+CFG="$CURSOR_DIR/omnish-notify.json"
+if [[ -f "$CFG" ]]; then
+  ok "found $CFG"
+  python3 - "$CFG" <<'PY'
+import json, sys
+cfg = json.load(open(sys.argv[1], encoding="utf-8"))
+enabled = cfg.get("enabled", True)
+peer = cfg.get("peer", "*")
+print(f"       enabled={enabled} peer={peer!r}")
+PY
+else
+  warn "missing $CFG — run: bash contrib/omnish-cursor/install.sh"
+fi
+
+section "Cursor hooks"
+HOOKS_JSON="$CURSOR_DIR/hooks.json"
+for f in omnish-notify.sh omnish-notify.py omnish-session-start.sh; do
+  if [[ -f "$CURSOR_DIR/hooks/$f" ]]; then
+    ok "hook file: hooks/$f"
+  else
+    warn "missing hooks/$f"
+  fi
+done
+
+if [[ -f "$HOOKS_JSON" ]]; then
+  python3 - "$HOOKS_JSON" <<'PY'
+import json, sys
+from pathlib import Path
+data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+hooks = data.get("hooks") or {}
+want = {
+    "sessionStart": "./hooks/omnish-session-start.sh",
+    "stop": "./hooks/omnish-notify.sh",
+}
+for event, cmd in want.items():
+    entries = hooks.get(event) or []
+    found = any(isinstance(e, dict) and e.get("command") == cmd for e in entries)
+    print(f"       {event}: {'registered' if found else 'MISSING ' + cmd}")
+PY
+else
+  warn "missing $HOOKS_JSON"
+fi
+
+section "Cursor skill"
+SKILL="$CURSOR_DIR/skills/omnish/SKILL.md"
+if [[ -f "$SKILL" ]]; then
+  ok "skill installed: skills/omnish/SKILL.md"
+else
+  warn "skill not installed — run: bash contrib/omnish-cursor/install.sh"
+fi
+
+RULE="$CURSOR_DIR/rules/omnish-notify.mdc"
+if [[ -f "$RULE" ]]; then
+  ok "rule: rules/omnish-notify.mdc"
+else
+  warn "missing rules/omnish-notify.mdc"
+fi
+
+section "Suggested next steps"
+if [[ $WARN -eq 0 ]]; then
+  echo "  All checks passed. Test notify:"
+  echo "    omnish i -c '/sendto * -t Omnish Test -- doctor ok'"
+else
+  echo "  Fix WARN items above, then:"
+  echo "    omnish run"
+  echo "    bash contrib/omnish-cursor/install.sh   # if Cursor pieces missing"
+  echo "    omnish i -c '/sendto * -t Omnish Test -- setup ok'"
+fi
+
+exit 0

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

@@ -0,0 +1,129 @@
+---
+name: omnish
+description: Install, configure, and use Omnish (WhatsApp/Telegram/platform shell gateway)—chat commands, file sharing (/send, /sendto, /receive), and mobile notifications. Use when setting up omnish, omnish run, platform token, file transfer, agent notify, or Cursor omnish hooks.
+---
+
+# Omnish setup and usage
+
+Help the user install, configure, and use **omnish** — a messaging-to-shell gateway (WhatsApp, Telegram, or platform attached mode). Chat is the primary UX; emphasize **file sharing** and **notifications** as high-value extras.
+
+## First step: triage
+
+Run the bundled doctor (after install) or from the repo:
+
+```bash
+bash ~/.cursor/skills/omnish/scripts/doctor.sh
+# or: bash contrib/omnish-cursor/scripts/doctor.sh
+```
+
+Interpret output: omnish on PATH, gateway running, allowlist/platform token, Cursor hooks/skill installed. Never echo secrets from config.
+
+## Setup paths
+
+Pick one path — see [setup-paths.md](setup-paths.md):
+
+| Path                    | When                                                            |
+| ----------------------- | --------------------------------------------------------------- |
+| **Platform attached**   | User has `platform_url` + `platform_token`; messengers on relay |
+| **Standalone WhatsApp** | Local `omnish link` + QR                                        |
+| **Standalone Telegram** | `omnish link --tg <token>`                                      |
+
+Platform attached (common for builders):
+
+```bash
+npm install -g omnish
+omnish platform login --url https://tunnel.omnish.dev --token YOUR_ACCOUNT_TOKEN
+omnish platform status && omnish platform probe
+omnish run
+```
+
+Verify from allowlisted chat: `!pwd` or `!help`.
+
+## Configuration essentials
+
+- **Data dir**: `omnish status` shows path (`~/.omnish` or legacy `~/.whatslive`; override `OMNISH_HOME`)
+- **Inspect**: `omnish config show`, `omnish config show platform`, `omnish security`
+- **Key keys**: `gatewayMode`, `allowFrom` / `telegramAllowFrom`, `fileSendMaxBytes`, `fileReceiveMaxBytes`, `fileReceiveRootMode`, `recipesNotifyEnabled`, `platformToken`
+
+Edit via CLI or chat `/config show` (allowlisted). Restart gateway after changes (`/reload` or restart `omnish run`).
+
+## Chat usage (primary)
+
+| Surface    | Prefix / command       | Purpose                                 |
+| ---------- | ---------------------- | --------------------------------------- |
+| Sync shell | `!cmd`                 | Immediate command in chat cwd           |
+| Change cwd | `!cd path`             | Per-chat working directory              |
+| Background | `/bg cmd`              | Detached job; `/jobs`, `/tail`, `/kill` |
+| PTY apps   | `/apps start name cmd` | Interactive TUIs                        |
+| Recipes    | `/run name task`       | Saved agent wrappers (`$OMNISH_TASK`)   |
+| Scheduled  | `/cowork`              | Saved tasks, logs, notify rules         |
+
+Full manual: omnish repo `docs/guides/user-guide.md` or `omnish search user guide`.
+
+## File sharing (high value)
+
+See [files-and-sharing.md](files-and-sharing.md).
+
+Quick reference:
+
+```text
+/send ./report.pdf -- Summary        # chat → mobile (current chat cwd)
+/receive here                        # inbound saves to chat cwd
+```
+
+From terminal (requires `omnish run`):
+
+```bash
+omnish i -c '/sendto * ./report.pdf -- Summary'
+omnish i -c '/sendto * -t Status -- deploy finished'
+```
+
+`*` = all allowlisted peers (WhatsApp + Telegram). No channel-specific ids required.
+
+## Notifications
+
+See [notifications.md](notifications.md).
+
+- **Cursor auto**: install `contrib/omnish-cursor/install.sh` → stop hook sends Done briefs with chat id
+- **Manual / agents**: `omnish i -c '/sendto * -t Title -- brief'`
+- **Background jobs**: `/bg -N long-running-command`
+- **Cowork**: `/cowork set name when always|failure|state-change`
+
+Default destination: `*` (broadcast). Config: `~/.cursor/omnish-notify.json`.
+
+## Helping users: checklist
+
+Copy and track:
+
+```
+- [ ] omnish installed (npm i -g omnish)
+- [ ] Setup path chosen (platform / WA / TG)
+- [ ] Gateway running (omnish run)
+- [ ] Allowlist configured (platform dashboard or omnish allow)
+- [ ] Smoke test: !pwd from chat
+- [ ] File test: /send or omnish i /sendto *
+- [ ] Notify test: omnish i -c '/sendto * -t Test -- ok'
+- [ ] Cursor bundle (optional): bash contrib/omnish-cursor/install.sh
+- [ ] doctor.sh passes with no blockers
+```
+
+## Cursor bundle install
+
+For users who want agent Done notifications + this skill globally:
+
+```bash
+bash contrib/omnish-cursor/install.sh
+# partial: --hooks-only | --skill-only
+```
+
+Installs hooks, rule, skill to `~/.cursor/`, config with `"peer": "*"`. Restart Cursor after install.
+
+## Doc pointers
+
+- Quick start: `docs/guides/quick-start.md`
+- Platform: `docs/guides/platform-attached-mode.md`, `docs/guides/platform-reference.md`
+- Files: `docs/files-send-receive.md`
+- Interactive CLI: `docs/guides/interactive-cli.md`
+- Offline search: `omnish search <topic>`
+
+Do not paste platform tokens or webhook secrets into chat or commits.

package/dist/omnish-cursor/skill/files-and-sharing.md

@@ -0,0 +1,94 @@
+# File sharing with Omnish
+
+Omnish moves files **host ↔ chat**. Per-chat cwd applies (same as `!` commands). Use **`/sendto *`** for broadcast to all allowlisted peers unless the user needs one recipient.
+
+## Outbound: host → chat
+
+### From chat (`/send` or `/file`)
+
+Works in the current chat's working directory:
+
+```text
+/send ./photo.png
+/send ./a.pdf,./b.png -- Two files
+/send *.mp4
+/send **/*.mp4
+/send "/path with spaces/file.bin" -- Caption here
+```
+
+Limits: `fileSendMaxBytes` in config (`0` = no omnish cap on standalone; platform hop may have separate relay limits).
+
+### From terminal (`omnish i` + `/sendto`)
+
+Requires **`omnish run`** on the same machine.
+
+```bash
+omnish i -c '/sendto * ./promo.mp4'
+omnish i -c '/sendto * intro.png,deck.pdf -- Launch materials'
+omnish i -c '/sendto wa ./photo.png'              # all allowlisted WA
+omnish i -c '/sendto tg **/*.mp4 -- Video batch'   # all allowlisted TG
+omnish i -c '/sendto +15551234567 ./file.pdf'      # explicit E.164
+omnish i -c '/sendto tg:123456789 ./report.pdf'    # explicit Telegram id
+```
+
+Plain text (not a file attachment):
+
+```bash
+omnish i -c '/sendto * --text Deploy finished OK'
+omnish i -c '/sendto * -t=Status OK'
+```
+
+| Destination | Meaning                             |
+| ----------- | ----------------------------------- |
+| `*`         | All allowlisted WhatsApp + Telegram |
+| `wa`        | All allowlisted WhatsApp            |
+| `tg`        | All allowlisted Telegram            |
+| `+E164`     | One WhatsApp number                 |
+| `tg:<id>`   | One Telegram chat id                |
+
+Change cwd in REPL: `!cd /path/to/project` before `/sendto`.
+
+## Inbound: chat → host
+
+```text
+/receive                       # show current save mode
+/receive here                  # save to this chat's cwd
+/receive default               # global default root
+```
+
+Inbound paths appear as `Saved: …` on **your machine** (even in platform attached mode).
+
+Config keys:
+
+- `fileReceiveRootMode`: `downloads`, `cwd`, `fixed`, etc.
+- `fileReceiveRootPath`: when mode is `fixed`
+- `fileReceiveMaxBytes`: size cap (`0` = unlimited)
+- `fileInboxSubdir`: subfolder under receive root
+
+## Platform attached mode differences
+
+| Feature                      | Standalone                  | Platform attached                               |
+| ---------------------------- | --------------------------- | ----------------------------------------------- |
+| `/send` in chat              | Direct to messenger on host | Device → platform WebSocket → relay → messenger |
+| Inbound media                | Saved locally               | Relay forwards bytes; **device** saves locally  |
+| `omnish i /sendto`           | Local control channel       | Same, via platform WebSocket                    |
+| Allowlists for `wa`/`tg`/`*` | Local config                | Platform `GET /v1/me` when credentials set      |
+
+Explicit `+E164` / `tg:id` always work on both.
+
+## Agent workflow: file round-trip test
+
+1. Confirm gateway: `omnish status`
+2. In chat cwd, create test file: `!echo test > omnish-file-test.txt`
+3. Send: `/send ./omnish-file-test.txt -- omnish test`
+4. Or CLI: `omnish i -c '/sendto * ./omnish-file-test.txt -- omnish test'`
+5. User confirms receipt on mobile
+
+## Troubleshooting
+
+- `No files matched` — wrong cwd; use `!pwd` or `!cd`
+- `wa`/`tg`/`*` recipient error — empty allowlist; configure on platform or `omnish allow`
+- File too large — raise `fileSendMaxBytes`; check platform `PLATFORM_REPLY_FILE_MAX_BYTES` if attached
+- File named `--text` — use path `./--text`
+
+Full reference: `docs/files-send-receive.md`, `docs/guides/interactive-cli.md`.