greprag 5.4.0 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "GrepRAG — agent memory for Claude Code. 2-command setup.",
   "main": "dist/index.js",
   "bin": {

package/skill/discord/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: discord
+description: |
+  Discord DM bridge for greprag. Pair your Discord account once, then DM the
+  bot to talk to the agent in any open Claude session. Handoff temporarily
+  pins your DMs to one specific session — say "let's continue on Discord"
+  before stepping away from the desk and your phone keeps the same thread
+  alive.
+
+  Use when: "/discord", "discord", "pair my discord", "step away", "let's
+  continue on discord", "let's continue on phone", "DM me", "handoff to
+  discord", "discord handoff", "discord status", "am I paired", "what's my
+  discord state", "I'm going for a walk", "I'll be afk".
+metadata:
+  author: travsteward
+  version: "1.0.0"
+  repository: https://github.com/travsteward/greprag
+license: MIT
+---
+
+# Discord DM bridge
+
+The agent runs `greprag discord me` to learn the current state, then branches into pair / handoff / status. Everything else is one shell command per branch.
+
+## Step 1 — Get the state
+
+```bash
+greprag discord me
+```
+
+Parse the JSON. Three states:
+
+- `paired: false` → user has never paired this tenant. Run **pair flow**.
+- `paired: true` and `handoff === null` → paired, no active pin. If the user asked to step away (any trigger phrase), run **handoff flow**. Otherwise just print **status**.
+- `paired: true` and `handoff !== null` → active pin live. Print **status with handoff details**.
+
+## Step 2 — Pair flow (only if not paired)
+
+```bash
+greprag discord pair
+```
+
+Prints the 6-char code. Tell the user verbatim:
+
+> DM `@greprag` on Discord: `/pair <CODE>` (expires in 15 min).
+
+When they confirm the bot replied with "Paired," re-run `greprag discord me` to verify, then continue. If the user wanted a handoff (their original request mentioned stepping away), proceed to Step 3 once paired.
+
+## Step 3 — Handoff flow (the killer feature)
+
+Trigger: user said anything implying "I'm leaving the desk and want this thread to follow me to Discord" — *step away*, *continue on phone*, *handoff*, *DM me*, *afk*, *I'll be walking*.
+
+Resolve the session id from the SessionStart hook's `additionalContext` (8-hex form). Resolve the project name from the current anchor (`greprag project-id`'s sibling lookup, or the explicit `--project` flag).
+
+Arm the watcher under **Monitor with `persistent: true`**, wrapped in the `while true` restart loop so a process death (npm install mid-session, network blip, supervisor bug) auto-recovers:
+
+```bash
+greprag discord handoff --session <8-hex> --project <name> --ttl 60 --no-watch && \
+while true; do
+  greprag inbox watch --project <name> --session <8-hex> --json --no-supervise
+  echo "[wrapper] watcher exited, restarting in 1s" >&2
+  sleep 1
+done
+```
+
+Two halves on purpose:
+1. `discord handoff --no-watch` writes the pin server-side (`active_project_id`, `active_session_id`, `active_expires_at`) and fires the confirmation DM to the user's phone. Returns immediately.
+2. The `while true` loop tails the session inbox via SSE. Each line printed = one Discord DM landing as a Monitor notification.
+
+**Never use the bare `greprag discord handoff` form without `--no-watch` for production handoff.** It self-streams, but a process death (e.g. `npm i -g greprag@latest` from another shell wipes the install dir) takes the watcher down with no restart. The wrapped two-step is the resilient form.
+
+Tell the user: "Handoff pinned for 60 min. Reply on Discord — your messages route to this session. Bot already DMed you a confirmation."
+
+## Step 4 — Replying to inbound DMs
+
+Each Monitor notification carries the full event payload: `body` is the user's message text, `references.discord.snowflake` is their Discord ID.
+
+Send your reply via the CLI:
+
+```bash
+greprag send --to discord:<snowflake> "your reply text"
+```
+
+The CLI uses Node fetch (UTF-8 native) — em-dashes, curly quotes, emoji all render correctly. **Do NOT use curl from bash on Windows** for Discord sends — the local code page (Win-1252) mangles non-ASCII bytes into `?` on the user's phone.
+
+For long agent turns where you're drafting >10s, refresh the typing indicator between work steps:
+
+```bash
+greprag discord typing
+```
+
+Silent on success. Tells Discord to show "GrepRAG is typing…" for another 10s.
+
+If the reply exceeds 2000 chars (Discord's hard limit), split on paragraph boundaries and send multiple messages with continuation markers.
+
+## Step 5 — Status (when paired with no handoff intent, or to inspect)
+
+Print verbatim:
+
+```
+Discord pairing:
+  Tenant:        travis (or whatever me.snowflake points to)
+  Default route: <me.project_name> (project_id <me.project_id>)
+  Snowflake:     <me.snowflake>
+  Paired at:     <me.paired_at>
+  Last DM in:    <me.last_seen_inbound_at or "(never)">
+```
+
+If `handoff !== null`:
+
+```
+Active handoff pin:
+  Project:    <me.handoff.project_name>
+  Session:    <me.handoff.session_id>
+  Expires:    <me.handoff.expires_at>  (sliding — each inbound DM extends by ≥30 min)
+```
+
+Offer: *"Run `greprag discord unhandoff` to clear the pin and revert DMs to default routing."*
+
+## Hard rules
+
+- **Don't auto-handoff without user intent.** If the user just asked "am I paired?", show status — don't arm a Monitor.
+- **Always use the wrapped form** in production. The bare `discord handoff` is for testing only.
+- **Send replies via the CLI**, not curl. UTF-8 correctness, parser correctness, and the success-print all break in subtle ways otherwise.
+- **Never `npm i -g greprag@latest`** from a session with a running handoff watcher — it kills the watcher mid-stream. Either land the upgrade before arming, or stop the Monitor first.
+- **Pin scope is one snowflake → one session at a time.** A new handoff in another session supersedes the prior one silently.
+
+## Related skills
+
+- `/greprag` — broader greprag setup (memory, inbox, corpus). Step 5g there carries the same handoff guidance for sessions invoked through greprag-as-orchestrator.
+- The `discord-notify` skill (separate, global) sends one-off Discord webhook pings for attention. Not related to this skill — that's a webhook, this is a paired DM bridge.