slack-term 1.24.0 → 1.26.0

package/README.md

@@ -54,13 +54,23 @@ slack news --limit 5
 # Recent messages across joined channels
 slack msgs
 
+# Channel/DM history. Thread parents are marked `[+N replies]`, so a line with
+# replies is distinguishable from one without — open it with `slack thread`.
+# --json adds reply_count / reply_users_count / latest_reply.
+slack read "#general"
+slack read "#general" --unreplied   # only threads/posts whose last word isn't yours
+
 # Search messages
 slack search "deploy"
 slack search "deploy" --count 50
 
 # Send a message (two-step confirm — quote #channel)
 slack send "#general" "Hello team"
-# Prints a destination preview + confirm code; rerun with --code=<code> to actually send
+# Prints who you're acting as (From: @handle (Uxxxx) — Workspace) + a destination
+# preview + confirm code; rerun with --code=<code> to actually send. Every gated write
+# (send/edit/delete/upload/schedule/channel create/drafts) shows that From: line and
+# binds it into the code, so a profile switch mid-flow invalidates it instead of acting
+# as the wrong account.
 slack send "#general" "Hello team" --code=<code>
 
 # Reply in a thread — #chan:<thread_ts>, or just paste a message permalink
@@ -71,7 +81,7 @@ slack send "https://acme.slack.com/archives/C0123456789/p1700000000000100" "Repl
 # Resolves via users.list, then the channel's members so Slack Connect guests work;
 # any handle that can't be resolved is left as plain text. The confirm preview shows
 # the converted message before sending. Use --no-mentions to keep @text literal.
-slack send "#general" "thanks @t.matsuda19790127 and @taku"
+slack send "#general" "thanks @t.yamada19850101 and @alice"
 slack send "#general" "ping @ops on call" --no-mentions   # leave @ops as plain text
 
 # Edit or delete a sent message (same confirm-code gate)
@@ -83,6 +93,14 @@ slack delete "<permalink>"
 slack react "#general:1700000000.000100" white_check_mark
 slack react "<permalink>" eyes --remove   # take a reaction back
 
+# Task tracking on top of reactions — :pushpin: marks a message as a task,
+# a second reaction carries its progress (see "todo" below)
+slack todo ls                                  # my open tasks
+slack todo ls --state untriaged --in "#general"
+slack todo set "#general:1700000000.000100" doing
+slack todo flag "<permalink>" blocked
+slack todo doctor --in "#general"              # find messages stuck in two states
+
 # Bulk export channel history
 slack dump --days 7 --filter eng
 
@@ -94,6 +112,98 @@ slack tail "#general" --me          # only messages that mention you
 slack tail "@bob" --exit-on-message --timeout 30m   # wait for a reply, then exit
 ```
 
+### todo — task tracking on reactions
+
+Tasks are just messages. A **marker** reaction (📌 `:pushpin:`) says "this is a task";
+a **progress** reaction says where it stands; **reason flags** stack on top:
+
+| axis | reaction | meaning |
+| --- | --- | --- |
+| progress 1 | ✅ `white_check_mark` | done |
+| progress 2 | 🚫 `no_entry_sign` | dropped |
+| progress 3 | 👀 `eyes` | doing |
+| progress 4 | ⏳ `hourglass_flowing_sand` | pending |
+| progress 5 | *(marker only)* | undefined / untriaged |
+| flag | ❗ `exclamation` | alert |
+| flag | ❓ `question` | needs discussion |
+| flag | 💬 `speech_balloon` | waiting — the other party in this conversation owes a reply |
+| flag | 🔒 `lock` | blocked — stuck on something *outside* this conversation |
+
+The invariant is **"at least one progress reaction, readers collapse by priority"** —
+not "exactly one". A message carrying both ✅ and 👀 reads as *done*.
+
+**Whose ball is it?** There are only three answers, and `pending` ⏳ already means *mine*.
+The other two are the flags:
+
+- 💬 **waiting** — I've done my part; someone **in this conversation** owes the next move
+  (I asked a question, I'm waiting on a review, I sent it and need a yes/no).
+- 🔒 **blocked** — the hold-up is **outside this conversation**: another task, a third
+  party, an external dependency, a deploy window.
+
+They stack with each other and with ❗/❓; `--state stuck` matches a task with any of them.
+
+```sh
+# Two listings, split by whose reactions count — the distinction is the command,
+# not a flag, so "everyone's list" and "my list" can't be confused at a glance.
+slack todo ls                              # EVERYONE's tasks (has:)
+slack mytodo ls                            # only tasks YOU reacted to (hasmy:)
+
+slack todo ls --state untriaged            # marked, no progress reaction yet
+slack todo ls --state doing --in "#eng"    # scoped to a channel
+slack mytodo ls --state stuck              # my unfinished tasks carrying a reason flag
+slack todo ls --state stuck --from "@alice" # …and it was alice who wrote it
+slack todo ls --from me                    # tasks on my own messages (any reactor)
+slack todo ls --mine                       # same as `slack mytodo ls`
+slack todo set "#eng:1700000000.000100" doing
+slack todo flag "<permalink>" waiting          # their ball now
+slack todo flag "<permalink>" needs-discussion
+slack todo flag "<permalink>" blocked --remove
+slack todo doctor --in "#eng"              # report messages in two progress states
+slack todo doctor --in "#eng" --fix        # keep the highest-priority one
+```
+
+Notes:
+
+- **`todo ls` vs `mytodo ls`** — `todo ls` matches anyone's reactions (`has:`), `mytodo ls`
+  only your own (`hasmy:`). Everything else about them is identical. Both print a
+  `From: @handle (Uxxxx) — Workspace` line first, because `hasmy:` resolves against
+  whichever account the token belongs to — "my tasks" means nothing until you know who
+  *my* is, and a stale profile otherwise lists someone else's list without saying so.
+  (`todo ls --mine` is a one-off shortcut to the narrow view.)
+- Both are read-only and run **exactly one** `search.messages` call — priority is expressed
+  as negated `has:`/`hasmy:` terms in the query, not as multiple searches
+  (`search.messages` is Tier 2, ~20 req/min). Slack's search index lags a little
+  behind `reactions.add`, so a just-set task may take a moment to appear.
+- `todo set` **adds the new reaction before removing the old ones**, and removes serially.
+  The reverse order would leave a window with no progress reaction at all — a crash or a
+  429 there would drop the task out of every query with nothing left pointing at it.
+  Worst case here is a message with two progress reactions, which reads correctly and is
+  repairable with `todo doctor --fix`.
+- `--from <@user|me>` maps to search's `from:` modifier (a missing `@` is supplied; `me`
+  passes through as-is). Reactions carry no reference to *whom* a task waits on, but the
+  sender is usually that person — so filtering by author answers most of the question for
+  free. It composes with `--in` in the same single search.
+- **Not implemented, deliberately:** encoding the actual reference ("blocked on @alice" /
+  "blocked on task X") as a machine-readable token in a thread reply. Measured: Slack's
+  full-text index splits on punctuation, so a quoted search for `"blocked-on"` returns 0
+  hits, and `"1.91"` matches `1.91.0`. A token like `todo:v1 blocked-on=@alice` is therefore
+  unsearchable. Any future attempt needs a single alphanumeric marker word (e.g. `tdblock`)
+  plus a bare `@mention`.
+- `todo doctor` pages history sequentially and scans at most `--limit` messages
+  (default 1000); if it hits the limit it says so rather than silently stopping.
+- Emoji are configurable in `~/.config/slack-cli/todo.json` (same directory as
+  `profiles.json`); anything omitted falls back to the defaults above:
+
+  ```json
+  { "marker": "round_pushpin", "progress": { "doing": "construction" } }
+  ```
+
+- Channel-name→ID and user-ID→handle lookups are cached in
+  `~/.config/slack-cli/cache.json` for 1 hour, namespaced by workspace (`team_id`) since
+  both are workspace-scoped; `--no-cache` bypasses it. Reaction state and search results
+  are **never** cached — they are exactly the values that change, and Slack's search index
+  already lags. A corrupt or unwritable cache is ignored and the command runs uncached.
+
 ### tail — real-time message stream
 
 `slack tail` polls a channel every 3 seconds (configurable via `--interval`) and
@@ -101,10 +211,10 @@ prints new messages as they arrive, in the same `[ts]  @handle:  text` format as
 the `read` command.
 
 ```sh
-slack tail "#symval"               # follow new messages from now
-slack tail "#symval" --since=30m   # backfill 30 minutes, then stream
-slack tail "#symval" --thread=1700000000.000100   # one thread only
-slack tail "#symval" --me          # only messages mentioning you
+slack tail "#general"               # follow new messages from now
+slack tail "#general" --since=30m   # backfill 30 minutes, then stream
+slack tail "#general" --thread=1700000000.000100   # one thread only
+slack tail "#general" --me          # only messages mentioning you
 ```
 
 For automation, `--exit-on-message` stops as soon as the first message from
@@ -113,7 +223,7 @@ For automation, `--exit-on-message` stops as soon as the first message from
 make a "wait for a reply, then act" primitive that won't hang:
 
 ```sh
-slack tail "@matsuda" --exit-on-message --timeout 30m --interval 15000
+slack tail "@alice" --exit-on-message --timeout 30m --interval 15000
 ```
 
 **Note:** Cross-channel mention streaming (`--me` without a target) is not yet
@@ -186,6 +296,19 @@ delivery (3-second interval). Supports `--since=<duration>` for backfill,
 that mention you. Uses `conversations.history?oldest=<ts>` as a cursor so
 already-seen messages are never re-printed, even across reconnects.
 
+## Ecosystem
+
+This CLI is the human-comms surface of the
+[agent-yes](https://github.com/snomiao/agent-yes) fleet: agent-yes runs, watches and
+delegates to AI coding agents, and `slack` is how they read and answer the humans they
+work with. Neither depends on the other — they share a stance rather than a library:
+file-based state over daemons, one command surface across two runtimes, gates on the
+irreversible and warnings on the merely unwise, and no real operational data in a public
+repo.
+
+A write-up of the design decisions behind the confirm gate lives on the agent-yes lab:
+[A confirm code that goes stale](https://lab.agent-yes.com/2026-08-11-slack-term-safe-writes).
+
 ## Related / prior art
 
 - [`slkcli`](https://www.npmjs.com/package/slkcli) by

package/SKILL.md

@@ -8,11 +8,15 @@ description: "Terminal Slack CLI — read news/mentions/DMs/channel history, ful
 A lightweight Slack CLI for quick workspace interaction from the terminal.
 Two implementations share one command surface (parity-tested):
 
-- **TypeScript** (bun-first), published as `@snomiao/slack` on npm.
+- **TypeScript** (bun-first), published as `slack-term` on npm.
 - **Rust** native binary, installable via `cargo install`.
 
 Binary name: `slack` (also aliased as `sl` / invoked via `sc sl ...` in some setups).
 
+Part of the [agent-yes](https://github.com/snomiao/agent-yes) ecosystem — this is the CLI an
+agent uses to talk to humans. Design notes:
+[lab.agent-yes.com](https://lab.agent-yes.com/2026-08-11-slack-term-safe-writes).
+
 ## When to use
 
 - User wants to read Slack activity, mentions, DMs, or channel history without opening the Slack app.
@@ -25,10 +29,13 @@ Binary name: `slack` (also aliased as `sl` / invoked via `sc sl ...` in some set
 TypeScript (recommended — any platform with Node 18+):
 
 ```sh
-npm install -g @snomiao/slack
-# or: bun add -g @snomiao/slack / pnpm add -g @snomiao/slack
+npm install -g slack-term
+# or: bun add -g slack-term / pnpm add -g slack-term
 ```
 
+> Previously published as `@snomiao/slack`; that name is deprecated on npm and
+> no longer updated. Install `slack-term`.
+
 Rust (native binary):
 
 ```sh
@@ -55,6 +62,10 @@ slack search "deploy" --count 50
 # Read a specific channel or DM (quote #channel — unquoted # is a shell comment)
 slack read "#general"
 slack read @username
+# Thread parents are marked `[+N replies]` — a marked line means there is more to
+# read inside the thread (`slack thread "#general" <ts>`); top-level output alone
+# never shows thread replies. --json carries reply_count/reply_users_count/latest_reply.
+slack read "#general" --unreplied   # only what's still awaiting your answer
 
 # Send a message (two-step confirm)
 slack send "#general" "Hello team"
@@ -74,6 +85,17 @@ slack delete "<permalink>"
 slack react "#general:1700000000.000100" white_check_mark
 slack react "<permalink>" eyes --remove   # take it back
 
+# Task tracking on reactions — 📌 marks a task, a second reaction holds progress
+slack todo ls                                     # EVERYONE's open tasks (has:)
+slack mytodo ls                                   # only tasks YOU reacted to (hasmy:)
+slack todo ls --state untriaged --in "#general"   # marked but no progress yet
+slack mytodo ls --state stuck                     # my unfinished tasks + a reason flag
+slack todo set "#general:1700000000.000100" doing # pending|doing|done|dropped
+slack todo ls --state stuck --from "@alice"        # …and alice wrote it
+slack todo flag "<permalink>" waiting             # alert|needs-discussion|waiting|blocked
+                                                  # waiting = their ball, blocked = outside
+slack todo doctor --in "#general" [--fix]         # messages stuck in two states
+
 # Bulk export a channel's history
 slack dump "#channel-name"
 
@@ -85,11 +107,24 @@ slack download "https://acme.slack.com/files/U1/F0123ABC/invoice.pdf"
 
 Targets for `send` are `#channel`, `@user`, `#channel:<thread_ts>`, or a Slack URL —
 a message permalink replies in that message's thread; a channel-only URL posts top-level.
-The confirm preview prints the resolved destination (`→ ... — THREAD REPLY` or
-`→ ... — NEW top-level message`); verify it before re-running with `--code`.
+The confirm preview prints who it will be sent **as** (`From: @handle (Uxxxx) — Workspace`,
+plus `[as bot]` under `--as-bot`) and the resolved destination (`→ ... — THREAD REPLY` or
+`→ ... — NEW top-level message`); verify both before re-running with `--code`.
+
+**Every** gated write opens its preview with that same `From:` line — `send`, `edit`,
+`delete`, `upload`, `schedule send`, `schedule rm`, `channel create`, `drafts edit`,
+`drafts delete` — and the identity is part of the confirm hash: switching
+profile/token between preview and confirm invalidates the code instead of acting as
+someone else. It matters most on `schedule send`, where the message goes out later,
+unattended, as whoever the token was at schedule time.
+
+`schedule send` prints its fire time in both zones —
+`At:  2026-08-10 18:00:00 GMT+9 (local) / 2026-08-10T09:00:00.000Z (Unix: 1786352400)` —
+because `--at` accepts both bare local times (`"2026-08-10 09:00"`) and `Z`-suffixed
+UTC, and the two are easy to mix up. Check the side you meant before confirming.
 
 `send` also runs a **warn-only untagged-mention lint**: if the body names a workspace
-member in plain text (honorifics like `松田さん` / `張老师`, or `Hi Dave`) without a
+member in plain text (honorifics like `山田さん` / `王老师`, or `Hi Dave`) without a
 matching `<@USERID>` tag, it prints `⚠ possible untagged mention: …` alongside the
 confirm code. It never blocks — third-party/external references are expected to trip it.
 To actually notify someone, write `@handle` (auto-converted to `<@USERID>`; see below).
@@ -103,8 +138,57 @@ and no one has replied since — `⚠ 相手はまだ返信していません…
 on that message instead of piling on a new one. Reply-status based, not time-based; opt
 out with `SLACK_UNREPLIED_WARN=0`.
 
+### todo — tasks as reactions
+
+A task is any message carrying the marker reaction 📌 `:pushpin:`. Progress lives in a
+second reaction, ranked by priority — **1** ✅ `white_check_mark` done, **2** 🚫
+`no_entry_sign` dropped, **3** 👀 `eyes` doing, **4** ⏳ `hourglass_flowing_sand` pending, **5** marker
+only = undefined. A message may carry more than one progress reaction — readers collapse
+to the highest priority, so ✅+👀 reads as *done*.
+
+Reason flags stack independently of progress and of each other: ❗ `exclamation` alert,
+❓ `question` needs-discussion, and two that say **whose ball it is** —
+
+- 💬 `speech_balloon` **waiting** — someone **in this conversation** owes the next move
+  (asked a question, waiting on a review/approval). Their ball.
+- 🔒 `lock` **blocked** — stuck on something **outside** it: another task, a third party,
+  an external dependency. Nobody here can unstick it by replying.
+
+(⏳ `hourglass_flowing_sand` pending already means "my ball", which is why only these two are needed.)
+
+- **`todo ls` = anyone's reactions (`has:`), `mytodo ls` = only yours (`hasmy:`).** Two
+  commands rather than a flag, so the two lists can't be mistaken for each other. Both
+  print `From: @handle (Uxxxx) — Workspace` first: `hasmy:` resolves against whoever the
+  token is, so "my tasks" is only meaningful once you know who *my* is. `todo ls --mine`
+  is a shortcut to the narrow view; `--shared` is accepted but is now the default.
+- Both are read-only and issue **one** `search.messages` call; priority is encoded as
+  negated `has:`/`hasmy:` terms.
+  `search.messages` returns no reaction data, so this filtering can only happen in the
+  query. The search index lags slightly behind `reactions.add`.
+- `todo set` adds the target reaction **first**, then removes the stale ones one at a time.
+  Never remove-then-add: an interruption in between leaves the task with no progress
+  reaction and it vanishes from every query. Two reactions is the safe failure mode, and
+  `todo doctor --fix` repairs it (also add-first).
+- `todo ls --from <@user|me>` adds search's `from:` modifier (missing `@` supplied, `me`
+  left bare) and composes with `--in` in the same single search. Reactions can't point at
+  *who* a task waits on, but the sender usually is that person.
+- Deliberately NOT implemented: a machine-readable token in a thread reply to carry the
+  actual reference. Measured — Slack's index splits on punctuation, so quoted `"blocked-on"`
+  gets 0 hits and `"1.91"` matches `1.91.0`; `todo:v1 blocked-on=@alice` is unsearchable.
+  A future attempt needs one alphanumeric marker word (e.g. `tdblock`) + a bare `@mention`.
+- `todo doctor` scans at most `--limit` messages (default 1000), pages sequentially, and
+  explicitly reports when it hits the limit.
+- Emoji overrides: `~/.config/slack-cli/todo.json`, e.g.
+  `{ "marker": "round_pushpin", "progress": { "doing": "construction" } }`.
+- Channel/user lookups are cached for 1h in `~/.config/slack-cli/cache.json`, keyed by
+  workspace `team_id` (`--no-cache` to bypass). Reaction state and search results are never
+  cached; a broken cache is ignored. Message listings read this cache too, behind their
+  in-process map.
+- Rate limits: `todo` commands catch Slack's 429, wait `Retry-After`, and retry up to 3
+  times before failing loudly.
+
 **Etiquette:** prefer a `react` over a reply for simple acks (了解 → `eyes`, 完了 →
-`white_check_mark`, 処理中 → `hourglass`) so threads stay short; read the thread with
+`white_check_mark`, 処理中 → `hourglass_flowing_sand`) so threads stay short; read the thread with
 `slack thread`/`slack read` before replying to avoid duplicates; consolidate multiple
 points into one message.
 
@@ -177,7 +261,7 @@ slack news --limit 1
 - **`xoxc-` desktop session token** — accepted by the public Slack API (send/edit/delete/react/upload/channel create+invite included) as long as its `xoxd` session cookie is attached (`slack auth chrome`/`slack auth firefox`, or `SLACK_COOKIE=...`). Without the cookie it still fails with a clear "needs its session cookie" error.
 - **`conversations.invite` reports success but the member never shows up** — the invited user is likely a single-channel guest (`is_ultra_restricted`); Slack silently no-ops the invite since that account type can only ever belong to the one channel it was created in. `channel create --invite` now warns about this up front.
 - **Send is rejected with "use #channel or @user"** — the CLI enforces human-readable targets. Use `#channel-name` or `@display-name`, not raw IDs.
-- **Confirm code mismatch on `send`** — the message text or destination changed between preview and confirm. Re-run without `--code` for a fresh preview, and re-check the `→` destination line (THREAD REPLY vs NEW top-level message).
+- **Confirm code mismatch on any gated write** — the content, target or acting identity changed between preview and confirm (a different profile/`SLACK_TOKEN`, or `--as-bot` added or dropped). Re-run without `--code` for a fresh preview, and re-check the `From:` line and the `→` destination line (THREAD REPLY vs NEW top-level message).
 - **Enterprise Grid / admin-locked workspace** — custom app installation may need admin approval or be disabled outright.
 
 ## Safety