slack-term 1.42.0 → 1.43.0

package/README.md

@@ -380,6 +380,82 @@ slack tail "@alice" --exit-on-message --timeout 30m --interval 15000
 **Note:** Cross-channel mention streaming (`--me` without a target) is not yet
 supported — a target channel is required.
 
+### stream — every matching message, across all channels
+
+`slack stream --grep <regex>` watches **every** conversation the identity is in —
+new top-level posts *and* thread replies — and prints each message whose text
+matches. It is the cross-channel counterpart of `tail`, built for a long-running
+consumer (e.g. "wake an agent whenever someone @mentions the bot"):
+
+```sh
+slack stream --grep '<@U00000001>|@mybot' --json            # runs until stopped
+slack stream --grep 'deploy' -i --channel '#dev' --once       # one scan, then exit
+slack stream --grep '<@U00000001>' --since 2h --json          # replay the last 2 hours
+slack stream --grep '<@U00000001>' --replies-to self --json   # + every reply in threads the bot is in
+```
+
+- **One JSON line per match** with `--json`:
+  `{type: "message"|"reply", channel: {id, name}, ts, thread_ts, user: {id, name}, text, permalink, match}`,
+  where `match` is `"grep"` or `"replies-to"`.
+  `--grep` runs on the raw text (mentions look like `<@U…>`), plus legacy attachment
+  text; the emitted `text` has `&lt; &gt; &amp;` decoded.
+- **Privacy-safe defaults.** With a bot token (`SLACK_BOT_TOKEN`) it streams **as the
+  bot**, so it sees only channels the bot was invited to — never the user's DMs.
+  `--as-user` opts into the user identity. Matching happens before anything is
+  printed: a non-matching message is never printed, logged, or even name-resolved.
+- **Replies in a user's threads.** `--replies-to <user-id>` (repeatable; `self` = the
+  streaming identity) also prints every reply in a thread that user started or has
+  replied in, whether or not it matches `--grep` — people answer a bot in its thread
+  without tagging it. It matches Slack's `parent_user_id`, the parent's
+  `reply_users`, and the id's own replies the stream has seen (kept in the state
+  file for 30 days). `reply_users` lists at most five people, so a thread cut short
+  there is read once in full (as is one whose list is missing). A bot can appear
+  as its user id (`U…`) or bot id (`B…`); `self`, or a `B…` id, covers both. Polling only reaches threads inside `--thread-window`;
+  with the relay, a reply in an older thread is caught too.
+- **No self-echo.** Posts by the streaming identity are excluded by sender id (its user
+  id and bot id; with `--as-user`, the bot's posts too) — the same text from anyone
+  else still matches.
+- **Resumable.** A per-channel cursor (plus one per active thread) is saved under
+  `$XDG_STATE_HOME/slack-term/stream/` (one file per identity + grep + channels + `--replies-to`;
+  override with `--state`). A restart continues where it stopped: nothing lost,
+  nothing repeated. The first run starts *now*; `--since` replays from a point,
+  ignoring the saved cursor. Delivery is at-least-once only in one corner — a crash
+  between printing a match and saving the cursor repeats that line, so dedupe on
+  `channel.id + ts`. A lock file keeps two streams off the same state.
+- **Transport: the relay is the primary mode; polling is the fallback.** Deploy
+  [`worker/`](worker/) (a Cloudflare Worker on Slack's Events API — setup in
+  [worker/README.md](worker/README.md)) and set `SLACK_RELAY_URL` and
+  `SLACK_RELAY_TOKEN`: the stream then hears a *doorbell* — `{channel, ts, thread_ts}`,
+  no text — within a second of each post, reads that one message through the Web API
+  with its own token and runs it through the same `--grep`. While the relay is
+  connected the poll still runs, every `--reconcile` (default `5m`), as the safety net;
+  when the relay is down it goes back to `--interval`. Both paths share one record of
+  what was printed, so a message is never printed twice. The relay is used only when
+  streaming as the bot (it rings for the bot's channels) and never with `--once`.
+- **Polling fallback** (no relay configured, `--as-user`, or `--no-relay`). The stream
+  prints a `WARNING: polling mode` line on stderr, pointing to the relay setup. It
+  polls every `--interval` (default `45s`), paced to stay inside Slack's rate limits:
+  - every cycle reads each channel's history **from its cursor only** (new posts);
+  - each channel's whole `--thread-window` (default `3d`) — which shows which threads
+    gained replies, and only those threads are read — is re-read once per
+    `--thread-scan` (default `3m`), spread across cycles rather than all at once, so a
+    reply under an older parent can take up to `--thread-scan` to appear;
+  - a channel with no post inside the window skips that re-read, and such an idle
+    DM/MPIM (`--as-user`) is not read at all between `--thread-scan` periods;
+  - all `conversations.history` / `conversations.replies` calls share one token
+    bucket, `--calls-per-min` (default `40`, under Tier 3's ~50/min; 10 at once).
+  A message is held back until it is 5 s old, so a cursor never skips one Slack has
+  not made visible yet. Rate limits honour `Retry-After`.
+- **Not covered:** edits (a message edited *into* matching is not re-emitted), and —
+  without the relay — replies in a thread whose parent is older than `--thread-window`.
+- **Failures are loud and distinguishable.** A network/API error retries the cycle
+  with φ backoff (`2s·1.618ⁿ`, capped at 5 min), one stderr line per attempt; after
+  12 consecutive failures (≈16 min) it exits. A channel it cannot read is skipped with
+  one stderr line; if *every* channel fails, that is a failure, not "no matches".
+- **Exit codes** (same contract as `ask`): `0` matches printed (`--once`) or stopped by
+  SIGINT/SIGTERM; `2` `--once` found nothing; `3` transport/auth failure (stderr says
+  which); `1` bad arguments (e.g. an invalid regex).
+
 ## Configuration
 
 Requires a Slack user token (`xoxp-...`) with the following scopes:

package/SKILL.md

@@ -52,6 +52,15 @@ slack news --limit 5
 # Recent messages across joined channels
 slack msgs
 
+# Every new message matching a regex, across all channels + threads (long-running;
+# resumable cursor; as the bot when SLACK_BOT_TOKEN is set). Exit 0 match / 2 none / 3 failure.
+# Real time = the relay (primary mode): deploy worker/ (see worker/README.md) and set
+# SLACK_RELAY_URL + SLACK_RELAY_TOKEN. Without it the stream falls back to POLLING and
+# warns on stderr ("WARNING: polling mode") — a fallback only: paced (--calls-per-min 40),
+# cursor-only reads each --interval (45s), full --thread-window re-read every --thread-scan (3m).
+slack stream --grep '<@U00000001>|@mybot' --json
+slack stream --grep 'deploy' -i --once
+
 # Full-text search
 slack search "deploy"
 slack search "deploy" --count 50