slack-term 1.42.0 → 1.44.0

package/README.md

@@ -125,6 +125,11 @@ slack react "<permalink>" eyes --remove   # take a reaction back
 # one tap on an existing pill, no emoji picker. Same two-step confirm gate as send.
 # A ❓ "その他 (other)" pill always follows the choices: pressing it means "none of
 # these" and the answer comes as a reply (exit 5), not as the ❓ itself.
+# --explain (or SLACK_TERM_ASK_EXPLAIN=1) adds an ℹ️ "説明して (explain)" pill after ❓:
+# pressing it asks YOU to explain in the thread and is never an answer — the question
+# stays open. --wait/--waitFor say so on stderr and may post ONE thread note (once per
+# question) saying an explanation is coming; --explain-exit makes that exit 7.
+# --pending only reports a ℹ️ press — it posts nothing.
 # The instructions are posted in ja or en: --lang / SLACK_TERM_LANG, else the
 # answerers' Slack locale, else the question's own language, else $LANG, else ja.
 slack ask "@bob" "本番に出してよい?" "出してよい" "待って"
@@ -380,6 +385,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
@@ -169,6 +178,16 @@ without losing clicks. A reaction is durable state anyone can read back later.
   (`1️⃣ … 2️⃣ … 3️⃣ … ❓ その他 — スレッドで返信`) and seeds it after the keycaps. Pressing it
   is not an answer — `--wait` notes it on stderr and keeps waiting for the reply, which
   arrives as free text (exit `5`).
+- **ℹ️ is the "explain first" pill** — offered with `--explain` (or
+  `SLACK_TERM_ASK_EXPLAIN=1`; `--no-explain` overrides), listed under ❓ and seeded after
+  it. ❓ means "none fit, my answer follows"; ℹ️ means "I can't answer yet — explain".
+  It **never answers or closes** the question: no ✅, the pills stay. `--wait`/`--waitFor`
+  print who pressed it on stderr (`--json`: `explain: [user ids]`) and may post ONE thread
+  note per question saying an explanation is coming (the thread is the record — re-presses
+  and re-runs post nothing more). Then explain in the thread and keep collecting.
+  `--explain-exit` stops with exit `7` (stdout empty; `--json` `status: "explain"`) on the
+  run that posts that note, so a `--timeout 0` poller hears about it once. Only the
+  question's audience counts; bots and the asker are ignored.
 - **The instructions are posted in `ja` or `en`.** `--lang` (or `SLACK_TERM_LANG`) decides;
   otherwise the answerers' Slack locale when they all share one, else the language the
   question is written in, else the system locale, else `ja`. The confirm gate prints the
@@ -178,7 +197,7 @@ without losing clicks. A reaction is durable state anyone can read back later.
 - **Exit codes** are the contract: `0` answered (the answer alone on stdout), `2` nobody
   replied, `3` transport/config failure, `4` a reply matched several choices (stdout
   empty), `6` the question was **voided** (stop waiting), `5` a **free-text reply** that picked none of the offered choices — the reply
-  text is on stdout. Everything human-facing goes to stderr, so
+  text is on stdout. `7` (only with `--explain-exit`) — ℹ️ pressed, explain and collect again. Everything human-facing goes to stderr, so
   `ANS=$(slack ask … --wait)` is safe.
 - **A reply that chooses nothing is delivered, but is not a decision.** When choices were
   offered, only a reaction, the choice text, or its number is a decision (`0`). A reply
@@ -245,7 +264,8 @@ an answer can be pressed and nobody ever hears about it.
 collected, and lists the ones somebody answered — grouped by the asking session, with
 the agent pid and whether it is still alive (pid running, started before the ask, same
 CLI), and per item the exact `collect:` line to run (cursor included). It is read-only —
-nothing is posted, edited, stamped or relayed. Collecting is that `slack ask --waitFor=…`
+nothing is posted, edited, stamped or relayed (an ℹ️ explain request is reported on
+stderr, but its thread note is left to `--wait`/`--waitFor`). Collecting is that `slack ask --waitFor=…`
 line: an answer it hands over (exit 0) takes the ask off the list; a free-text reply it
 hands over (exit 5) is not reported again, but a pill pressed after it is.