slack-term 1.45.0 → 1.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"

package/ts/botIntent.ts

@@ -15,6 +15,7 @@ const WRITES = new Set([
   "schedule send", "schedule rm",
   "pinlog new", "pinlog set", "pinlog note", "pinlog pin",
   "todo set", "todo flag",
+  "todos add", "todos done", "todos complete", "todos edit", "todos rm", "todos remove", "todos delete",
   "lists create", "lists add", "lists set", "lists share",
   "drafts new", "drafts save", "drafts edit", "drafts update", "drafts delete", "drafts rm",
   "channel create", "channel new", "channel rename", "channel mv",

package/ts/cli.ts

@@ -14,7 +14,7 @@ import { diagnoseBotMessaging, formatDiagnosis } from "./botdoctor.ts";
 import { cmdAuthLogin, cmdAuthLoginChrome, cmdAuthChrome, cmdAuthFirefox, cmdAuthToken, cmdAuthApp, cmdAuthSave, cmdAuthTokens } from "./auth.ts";
 import { cmdTail, parseSince as parseDuration } from "./tail.ts";
 import { runStream, webClient } from "./stream.ts";
-import { relaySubscriber } from "./relay.ts";
+import { relaySubscriber, relayTransport } from "./relay.ts";
 import { agentCommands } from "./agent.ts";
 
 import {
@@ -117,7 +117,10 @@ import {
   userName,
   getPath,
   type Json,
+  savedAdd,
+  savedDelete,
   savedList,
+  savedUpdate,
 } from "./slack.ts";
 import { isDone, messagePermalink, parseSavedItems, sortTodos, TODO_FILTERS, todoStatus, type TodoFilter, type TodoItem } from "./slackTodos.ts";
 import {
@@ -883,8 +886,13 @@ async function cmdDrafts(token: string, cookie?: string, showAll = false): Promi
 }
 
 // --- todos (Slack's To-dos tab) ---
-// Read-only. Pages through saved.list up to `limit` items, then shows each
-// to-do with its due date, where it lives, and the message it points at.
+// Read-only. Reads the whole view, sorts it by due date, then shows the first
+// `limit` with where each lives and the message it points at. saved.list does
+// not return items in due order, so cutting before sorting could hide an
+// overdue to-do behind a later one; the read is capped at TODOS_MAX_PAGES.
+const TODOS_PAGE = 50;
+const TODOS_MAX_PAGES = 20;
+
 async function cmdTodos(
   token: string,
   cookie: string | undefined,
@@ -892,12 +900,14 @@ async function cmdTodos(
 ): Promise<void> {
   const items: TodoItem[] = [];
   let cursor: string | undefined;
+  let pages = 0;
   do {
-    const resp = asRecord((await savedList(token, { filter: opts.filter, limit: Math.min(opts.limit, 100), cursor }, cookie)) as Json);
+    const resp = asRecord((await savedList(token, { filter: opts.filter, limit: TODOS_PAGE, cursor }, cookie)) as Json);
     items.push(...parseSavedItems(resp as Json));
     const next = asRecord(resp.response_metadata).next_cursor;
     cursor = typeof next === "string" && next ? next : undefined;
-  } while (cursor && items.length < opts.limit);
+  } while (cursor && ++pages < TODOS_MAX_PAGES);
+  if (cursor) console.error(`Note: read the first ${items.length} items only (${TODOS_MAX_PAGES} pages); the order covers those.`);
   const shown = sortTodos(items).slice(0, opts.limit);
 
   if (shown.length === 0) {
@@ -941,6 +951,139 @@ async function cmdTodos(
   }
 }
 
+// --- todos add / done / edit / rm — gated writes to your To-dos ---
+// Every To-do points at a message, so the target is a message (permalink or
+// #chan:<ts>). Same two-step as send: the first run previews and prints a code,
+// the rerun with --code=<code> writes. Your own To-dos only — the session token
+// can touch no one else's.
+type TodoOp =
+  | { kind: "add"; due?: number; saved?: boolean }
+  | { kind: "done"; undo: boolean }
+  | { kind: "edit"; due?: number; todo?: boolean }
+  | { kind: "rm" };
+
+// The saved item for one message (saved.delete answers ok even when there is
+// nothing to delete, so writes check first). Views are searched in the order
+// the op most likely needs, stopping at the first match, and the whole search
+// is capped at TODOS_MAX_PAGES pages so a long saved history can't turn one
+// command into a burst of saved.list calls. "unknown" = cap hit, not found.
+function findOrder(op: TodoOp): TodoFilter[] {
+  if (op.kind === "done") return op.undo ? ["completed", "todo", "saved", "archived"] : ["todo", "saved", "completed", "archived"];
+  return ["todo", "saved", "completed", "archived"];
+}
+
+async function findSavedItem(
+  token: string,
+  cookie: string | undefined,
+  channel: string,
+  ts: string,
+  order: TodoFilter[],
+): Promise<TodoItem | "unknown" | undefined> {
+  let pages = 0;
+  for (const filter of order) {
+    let cursor: string | undefined;
+    do {
+      if (pages++ >= TODOS_MAX_PAGES) return "unknown";
+      const resp = asRecord((await savedList(token, { filter, limit: TODOS_PAGE, cursor }, cookie)) as Json);
+      const hit = parseSavedItems(resp as Json).find((t) => t.channel === channel && t.ts === ts);
+      if (hit) return hit;
+      const next = asRecord(resp.response_metadata).next_cursor;
+      cursor = typeof next === "string" && next ? next : undefined;
+    } while (cursor);
+  }
+  return undefined;
+}
+
+function todoOpLines(op: TodoOp, fmtDue: (sec: number) => string): string[] {
+  const due = (d: number | undefined) => (d === undefined ? [] : [`  Due:    ${d ? fmtDue(d) : "(clear the due date)"}`]);
+  switch (op.kind) {
+    case "add": return [`  Action: add as ${op.saved ? "a saved item (no checkbox)" : "a to-do"}`, ...due(op.due)];
+    case "done": return [`  Action: mark ${op.undo ? "NOT done (reopen)" : "done"}`];
+    case "edit": return [
+      "  Action: edit",
+      ...(op.todo === undefined ? [] : [`  Kind:   ${op.todo ? "to-do" : "saved item (no checkbox)"}`]),
+      ...due(op.due),
+    ];
+    case "rm": return ["  Action: REMOVE from your To-dos (the message itself is untouched)"];
+  }
+}
+
+async function cmdTodosWrite(token: string, cookie: string | undefined, target: string, op: TodoOp, code?: string): Promise<void> {
+  const { ref, ts } = splitRefTs(target);
+  if (!ts) {
+    console.error("Error: a To-do points at a message — give its permalink or #chan:<ts> (see `slack todos ls`).");
+    process.exit(2);
+  }
+  if (op.kind === "edit" && op.due === undefined && op.todo === undefined) {
+    console.error("Error: nothing to edit — pass --due <time|none>, --todo or --saved.");
+    process.exit(2);
+  }
+  const channel = await resolveChannel(token, ref, cookie);
+  const found = await findSavedItem(token, cookie, channel, ts, findOrder(op));
+  if (found === "unknown" && op.kind !== "add") {
+    console.error(`Error: not found in the first ${TODOS_MAX_PAGES * TODOS_PAGE} saved items — stopped there to stay under Slack's rate limits. Nothing was changed.`);
+    process.exit(1);
+  }
+  const existing = found === "unknown" ? undefined : found;
+  if (op.kind === "add" && existing) {
+    console.error(`Error: that message is already in your To-dos (${isDone(existing) ? "done" : existing.todoState || "saved"}) — use \`slack todos edit\` or \`done\`.`);
+    process.exit(1);
+  }
+  if (op.kind !== "add" && !existing) {
+    console.error("Error: that message is not in your To-dos — nothing to change. `slack todos ls --filter saved` lists everything saved.");
+    process.exit(1);
+  }
+
+  let teamUrl = "";
+  let me = "";
+  try { ({ url: teamUrl, userId: me } = await authScopes(token, cookie)); } catch { /* preview degrades */ }
+  const label = await (await buildChLabelResolver(token, cookie, me))(channel);
+  let msg: Record<string, Json> | undefined;
+  try {
+    const r = asRecord((await replies(token, channel, ts, 1, cookie)) as Json);
+    msg = asArray(r.messages).map(asRecord).find((m) => m.ts === ts);
+  } catch { /* not readable */ }
+  const author = typeof msg?.user === "string" ? `@${await userName(token, msg.user, cookie)}: ` : "";
+  const raw = typeof msg?.text === "string" ? msg.text.split("\n")[0] ?? "" : "(message not readable)";
+  const head = maskSecrets(raw.length > 100 ? `${raw.slice(0, 100)}…` : raw);
+  const now = Date.now() / 1000;
+
+  const expected = safetyCode("todos", JSON.stringify(op), channel, ts, me);
+  if (code !== expected) {
+    requireCode(code, expected, [
+      "--- To-do ------------------------------------",
+      `  For:    ${me ? `@${await userName(token, me, cookie)} (your own To-dos)` : "(your own To-dos)"}`,
+      `  Where:  ${stripTerminalControls(label)}`,
+      `  Msg:    ${stripTerminalControls(author + head)}`,
+      ...(teamUrl ? [`  Link:   ${messagePermalink(teamUrl, channel, ts)}`] : []),
+      ...(existing ? [`  Now:    ${todoStatus(existing, now, formatYmdHm)}`] : []),
+      ...(found === "unknown" ? [`  Note:   not checked beyond the first ${TODOS_MAX_PAGES * TODOS_PAGE} saved items — it may already be saved`] : []),
+      ...todoOpLines(op, fmtPostAt),
+      "----------------------------------------------",
+    ]);
+  }
+
+  const at = { channel, ts };
+  switch (op.kind) {
+    case "add":
+      await savedAdd(token, at, { todo: !op.saved, ...(op.due ? { due: op.due } : {}) }, cookie);
+      console.log(`✓ Added to your To-dos${op.due ? ` (due ${formatYmdHm(op.due)})` : ""}`);
+      break;
+    case "done":
+      await savedUpdate(token, at, { mark: op.undo ? "uncompleted" : "completed" }, cookie);
+      console.log(op.undo ? "✓ Reopened" : "✓ Marked done");
+      break;
+    case "edit":
+      await savedUpdate(token, at, { ...(op.todo === undefined ? {} : { todo: op.todo }), ...(op.due === undefined ? {} : { due: op.due }) }, cookie);
+      console.log("✓ Updated");
+      break;
+    case "rm":
+      await savedDelete(token, at, cookie);
+      console.log("✓ Removed from your To-dos");
+      break;
+  }
+}
+
 // --- drafts get ---
 async function cmdDraftGet(token: string, cookie: string | undefined, draftId: string): Promise<void> {
   const resp = (await listDrafts(token, cookie)) as Record<string, Json>;
@@ -4752,6 +4895,16 @@ async function botDmForTarget(
   return openDm(botToken, userId);
 }
 
+/** A `--due` value as epoch seconds; exits 2 on an unparseable one. */
+function todoDue(v: string): number {
+  try {
+    return parsePostAt(v);
+  } catch {
+    console.error(`Error: cannot parse --due "${v}" — use an ISO datetime (2026-11-01T18:00) or a Unix ts.`);
+    process.exit(2);
+  }
+}
+
 function parsePostAt(at: string): number {
   if (/^\d{10,}$/.test(at)) return parseInt(at, 10);
   const d = new Date(at.replace(" ", "T"));
@@ -7147,7 +7300,7 @@ async function main(): Promise<void> {
     )
     .command(
       "todos",
-      "Slack's To-dos tab — your personal to-dos (read-only; requires xoxc desktop token). Not `slack todo` (reaction tasks)",
+      "Slack's To-dos tab — your personal to-dos (requires xoxc desktop token). Not `slack todo` (reaction tasks)",
       (y) => y.command(
         ["$0", "ls", "list"],
         "List your To-dos, soonest due first",
@@ -7162,7 +7315,59 @@ async function main(): Promise<void> {
           }
           await cmdTodos(tok(argv as W), ck(argv as W), { filter: argv.filter as TodoFilter, limit: argv.limit, json: argv.json });
         },
-      ),
+      )
+        .command(
+          "add <target>",
+          "Add a message to your To-dos (two-step: preview, then --code)",
+          (y2) => y2
+            .positional("target", { type: "string", demandOption: true, describe: "Message permalink or #chan:<ts>" })
+            .option("due", { type: "string", describe: "Due time (ISO datetime or Unix ts)" })
+            .option("saved", { type: "boolean", default: false, describe: "Save it without a checkbox instead of as a to-do" })
+            .option("code", { type: "string", describe: "Confirmation code from the preview" }),
+          async (argv) => {
+            const due = argv.due === undefined ? undefined : todoDue(argv.due);
+            await cmdTodosWrite(tok(argv as W), ck(argv as W), argv.target!, { kind: "add", ...(due ? { due } : {}), saved: argv.saved }, argv.code);
+          },
+        )
+        .command(
+          ["done <target>", "complete <target>"],
+          "Check a to-do off (--undo reopens it)",
+          (y2) => y2
+            .positional("target", { type: "string", demandOption: true, describe: "Message permalink or #chan:<ts>" })
+            .option("undo", { type: "boolean", default: false, describe: "Mark it not done again" })
+            .option("code", { type: "string", describe: "Confirmation code from the preview" }),
+          async (argv) => {
+            await cmdTodosWrite(tok(argv as W), ck(argv as W), argv.target!, { kind: "done", undo: argv.undo }, argv.code);
+          },
+        )
+        .command(
+          "edit <target>",
+          "Change a to-do's due date, or switch it between to-do and saved item",
+          (y2) => y2
+            .positional("target", { type: "string", demandOption: true, describe: "Message permalink or #chan:<ts>" })
+            .option("due", { type: "string", describe: "New due time (ISO datetime or Unix ts), or `none` to clear it" })
+            .option("todo", { type: "boolean", describe: "Make it a to-do (with a checkbox)" })
+            .option("saved", { type: "boolean", describe: "Make it a plain saved item (no checkbox)" })
+            .conflicts("todo", "saved")
+            .option("code", { type: "string", describe: "Confirmation code from the preview" }),
+          async (argv) => {
+            const due = argv.due === undefined ? undefined : argv.due === "none" ? 0 : todoDue(argv.due);
+            const todo = argv.todo ? true : argv.saved ? false : undefined;
+            await cmdTodosWrite(tok(argv as W), ck(argv as W), argv.target!, {
+              kind: "edit", ...(due === undefined ? {} : { due }), ...(todo === undefined ? {} : { todo }),
+            }, argv.code);
+          },
+        )
+        .command(
+          ["rm <target>", "remove <target>", "delete <target>"],
+          "Remove a message from your To-dos (the message stays)",
+          (y2) => y2
+            .positional("target", { type: "string", demandOption: true, describe: "Message permalink or #chan:<ts>" })
+            .option("code", { type: "string", describe: "Confirmation code from the preview" }),
+          async (argv) => {
+            await cmdTodosWrite(tok(argv as W), ck(argv as W), argv.target!, { kind: "rm" }, argv.code);
+          },
+        ),
     )
     .command(
       "drafts",
@@ -7548,7 +7753,7 @@ async function main(): Promise<void> {
         const relayUrl = process.env.SLACK_RELAY_URL;
         const relayToken = process.env.SLACK_RELAY_TOKEN;
         const relay = argv.relay && !asUser && !argv.once && relayUrl && relayToken
-          ? { url: relayUrl, subscribe: relaySubscriber(relayUrl, relayToken), reconcileMs }
+          ? { url: relayUrl, subscribe: relaySubscriber(relayUrl, relayToken, undefined, { transport: relayTransport(process.env.SLACK_RELAY_TRANSPORT) }), reconcileMs }
           : undefined;
         if (argv.relay && asUser && relayUrl) console.error("slack stream: relay not used with --as-user (it only sees the bot's channels)");
         const pollReason = !argv.relay ? "--no-relay"

package/ts/relay.ts

@@ -1,11 +1,17 @@
 // Client for the slack-term relay (worker/): a Cloudflare Worker that receives
 // Slack's Events API and serves "doorbells" — {channel, ts, thread_ts}, never
-// message text — as a resumable Server-Sent Events stream. `slack stream` uses
-// it to scan the one channel a bell names within a second of the post, instead
-// of waiting for its next poll.
+// message text — as a resumable stream. `slack stream` uses it to scan the one
+// channel a bell names within a second of the post, instead of waiting for its
+// next poll.
 //
-// SSE over fetch (not WebSocket) so the bearer token travels in a header on
-// both bun and node, and never in a URL.
+// Transport: a WebSocket to /ws first. The relay accepts it as a hibernatable
+// socket, so its Durable Object is not kept awake (and billed) while we sit
+// connected, and our 25 s "ping" is answered without waking it. The bearer
+// token never goes in a URL: it rides in the Sec-WebSocket-Protocol header as
+// `bearer.<base64url(token)>` — Node's WebSocket cannot set other headers.
+// If the socket cannot be opened at all (a relay from before /ws, a proxy
+// that strips upgrades, a runtime without WebSocket), the same connection
+// falls back to the old Server-Sent Events endpoint, /stream, over fetch.
 
 /** A bell: where a message just appeared. */
 export type Doorbell = {
@@ -18,7 +24,13 @@ export type Doorbell = {
  *  starts from; `gap` means bells after the requested seq are gone (expired,
  *  or the relay was reset), so the client must catch up by polling. `epoch`
  *  names the relay's storage: a new one means its numbering restarted. */
-export type Hello = { seq: number; gap: boolean; retention_sec: number; epoch?: string };
+export type Hello = {
+  seq: number; gap: boolean; retention_sec: number; epoch?: string;
+  /** Client-side: which transport this connection uses. */
+  via?: Transport;
+};
+
+export type Transport = "websocket" | "sse";
 
 /** Where to resume: the last seq taken, in the numbering of `epoch`. */
 export type Cursor = { seq: number; epoch?: string };
@@ -58,8 +70,158 @@ export function parseSse(buf: string, emit: (event: string, data: string, id: st
   return buf;
 }
 
-export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000): Subscribe {
+/** The subprotocol the relay's /ws speaks; it echoes this one back. */
+export const WS_PROTOCOL = "slack-term-relay.v1";
+
+/** The subprotocol that carries the bearer token: subprotocols must be HTTP
+ *  tokens, so the token is base64url-encoded. */
+export function bearerProtocol(token: string): string {
+  return `bearer.${Buffer.from(token, "utf8").toString("base64url")}`;
+}
+
+/** The slice of the WHATWG WebSocket this client uses (bun's and node's). */
+export type WebSocketLike = {
+  readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null;
+};
+export type WebSocketCtor = new (url: string, protocols: string[]) => WebSocketLike;
+
+export type RelayOptions = {
+  /** "auto" (default): WebSocket, falling back to SSE when it cannot open. */
+  transport?: "auto" | Transport;
+  /** Defaults to the runtime's global WebSocket; null means none. */
+  WebSocket?: WebSocketCtor | null;
+  /** Keepalive ping interval; the relay answers without waking up. */
+  pingMs?: number;
+  /** How long a received bell may wait for its ack (acks are batched). */
+  ackDelayMs?: number;
+};
+
+/** SLACK_RELAY_TRANSPORT: "websocket" or "sse" pins one; anything else is "auto". */
+export function relayTransport(v: string | undefined): "auto" | Transport {
+  return v === "websocket" || v === "sse" ? v : "auto";
+}
+
+/** Received-but-unacked bells that trigger an ack at once. The relay cuts a
+ *  client off at 64 unacked live bells, and replays its backlog one batch
+ *  per ack. */
+const ACK_EVERY = 32;
+
+function resumeQuery(after: Cursor | undefined): string {
+  return after === undefined ? "" : `?after=${after.seq}${after.epoch ? `&epoch=${encodeURIComponent(after.epoch)}` : ""}`;
+}
+
+export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000, opts: RelayOptions = {}): Subscribe {
   const base = baseUrl.replace(/\/+$/, "");
+  const transport = opts.transport ?? "auto";
+  const sse = sseSubscriber(base, token, idleMs);
+  return async (after, signal, on) => {
+    const WS = opts.WebSocket === undefined ? (globalThis as { WebSocket?: WebSocketCtor }).WebSocket : opts.WebSocket;
+    if (transport !== "sse") {
+      if (!WS) {
+        if (transport === "websocket") throw new Error("relay: this runtime has no WebSocket");
+      } else {
+        const opened = await wsSubscribe(WS, base, token, idleMs, opts.pingMs ?? 25_000, opts.ackDelayMs ?? 100, after, signal, on);
+        if (opened || signal.aborted) return;
+        // Never opened: an old relay, or something in between refusing the
+        // upgrade. SSE says which — a 401 from it is a RelayAuthError.
+        if (transport === "websocket") throw new Error("relay: WebSocket connection failed");
+      }
+    }
+    return sse(after, signal, on);
+  };
+}
+
+/** One WebSocket connection. Resolves true once it has been open (closed by
+ *  the server normally, or aborted), false if it never opened — the caller
+ *  then falls back to SSE. Rejects on an abnormal close or silence. */
+function wsSubscribe(
+  WS: WebSocketCtor, base: string, token: string, idleMs: number, pingMs: number, ackDelayMs: number,
+  after: Cursor | undefined, signal: AbortSignal, on: RelayHandlers,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve, reject) => {
+    if (signal.aborted) return resolve(true);
+    let ws: WebSocketLike;
+    try {
+      ws = new WS(`${base.replace(/^http/i, "ws")}/ws${resumeQuery(after)}`, [WS_PROTOCOL, bearerProtocol(token)]);
+    } catch {
+      return resolve(false);
+    }
+    let opened = false;
+    let done = false;
+    let idle: ReturnType<typeof setTimeout> | undefined;
+    let ackTimer: ReturnType<typeof setTimeout> | undefined;
+    let ping: ReturnType<typeof setInterval> | undefined;
+    let last = 0; // highest seq received
+    let acked = 0; // highest seq acked
+    const finish = (err?: Error): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(idle);
+      clearTimeout(ackTimer);
+      clearInterval(ping);
+      signal.removeEventListener("abort", onAbort);
+      ws.onopen = ws.onmessage = ws.onerror = ws.onclose = null;
+      try { ws.close(1000); } catch { /* already closing */ }
+      if (err) reject(err);
+      else resolve(opened || signal.aborted);
+    };
+    const onAbort = (): void => finish();
+    signal.addEventListener("abort", onAbort, { once: true });
+    const arm = (): void => {
+      clearTimeout(idle);
+      // Silence before the open is a handshake that hangs: fall back.
+      idle = setTimeout(() => finish(opened ? new Error(`relay: no data for ${Math.round(idleMs / 1000)}s`) : undefined), idleMs);
+    };
+    const ack = (): void => {
+      clearTimeout(ackTimer);
+      ackTimer = undefined;
+      if (last <= acked) return;
+      acked = last;
+      try { ws.send(JSON.stringify({ type: "ack", seq: last })); } catch { /* the close event reports it */ }
+    };
+    arm();
+    ws.onopen = () => {
+      opened = true;
+      arm();
+      ping = setInterval(() => { try { ws.send("ping"); } catch { /* the close event reports it */ } }, pingMs);
+    };
+    ws.onmessage = (ev) => {
+      arm();
+      if (typeof ev.data !== "string" || ev.data === "pong") return;
+      let m: { type?: unknown; seq?: unknown; bell?: unknown };
+      try {
+        m = JSON.parse(ev.data) as typeof m;
+      } catch (e) {
+        return finish(e as Error);
+      }
+      if (m.type === "hello") {
+        const { type: _, ...h } = m as Hello & { type: string };
+        last = acked = h.seq;
+        on.hello({ ...h, via: "websocket" });
+      } else if (m.type === "bell" && typeof m.seq === "number") {
+        on.bell(m.seq, m.bell as Doorbell);
+        if (done) return; // the handler hung up
+        last = Math.max(last, m.seq);
+        if (last - acked >= ACK_EVERY) ack();
+        else ackTimer ??= setTimeout(ack, ackDelayMs);
+      }
+    };
+    ws.onerror = () => { /* a close event follows */ };
+    ws.onclose = (ev) => {
+      if (!opened || ev.code === 1000) return finish();
+      finish(new Error(`relay: WebSocket closed (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})`));
+    };
+  });
+}
+
+/** The Server-Sent Events transport (GET /stream). */
+function sseSubscriber(base: string, token: string, idleMs: number): Subscribe {
   return async (after, signal, on) => {
     const ac = new AbortController();
     const stop = (): void => ac.abort();
@@ -72,8 +234,7 @@ export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000)
     };
     try {
       arm();
-      const q = after === undefined ? "" : `?after=${after.seq}${after.epoch ? `&epoch=${encodeURIComponent(after.epoch)}` : ""}`;
-      const res = await fetch(`${base}/stream${q}`, {
+      const res = await fetch(`${base}/stream${resumeQuery(after)}`, {
         headers: { authorization: `Bearer ${token}`, accept: "text/event-stream" },
         signal: ac.signal,
       });
@@ -89,7 +250,7 @@ export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000)
         // CRLF is normalised on the whole buffer: a \r\n pair can straddle chunks.
         buf = parseSse((buf + dec.decode(value, { stream: true })).replace(/\r\n/g, "\n"), (event, data, id) => {
           const j = JSON.parse(data) as unknown;
-          if (event === "hello") on.hello(j as Hello);
+          if (event === "hello") on.hello({ ...j as Hello, via: "sse" });
           else if (event === "bell" && id !== undefined) on.bell(Number(id), j as Doorbell);
         });
       }

package/ts/slack.ts

@@ -1119,6 +1119,38 @@ export async function savedList(
   return postSession(token, "saved.list", params, cookie);
 }
 
+// To-dos writes (internal, session token). Verified live 2026-10-26: add with
+// todo_state=to_do (+ date_due) creates a to-do; update mark=completed checks it
+// off (todo_state becomes "completed"); delete removes it. A To-do always
+// points at a message: item_type=message, item_id=channel, ts=message ts.
+export type SavedRef = { channel: string; ts: string };
+const savedIds = (r: SavedRef) => ({ item_type: "message", item_id: r.channel, ts: r.ts });
+
+export async function savedAdd(token: string, ref: SavedRef, opts: { todo?: boolean; due?: number } = {}, cookie?: string): Promise<Json> {
+  const params: Record<string, string> = { ...savedIds(ref), todo_state: opts.todo === false ? "saved" : "to_do" };
+  if (opts.due) params.date_due = String(opts.due);
+  return postSession(token, "saved.add", params, cookie);
+}
+
+/** `mark`: completed | uncompleted | archived | unarchived. `due`: epoch seconds, 0 clears it. */
+export async function savedUpdate(
+  token: string,
+  ref: SavedRef,
+  opts: { mark?: "completed" | "uncompleted" | "archived" | "unarchived"; todo?: boolean; due?: number },
+  cookie?: string,
+): Promise<Json> {
+  const params: Record<string, string> = savedIds(ref);
+  if (opts.mark) params.mark = opts.mark;
+  if (opts.todo !== undefined) params.todo_state = opts.todo ? "to_do" : "saved";
+  if (opts.due !== undefined) params.date_due = String(opts.due);
+  return postSession(token, "saved.update", params, cookie);
+}
+
+/** Slack answers ok even when nothing was saved — callers check first. */
+export async function savedDelete(token: string, ref: SavedRef, cookie?: string): Promise<Json> {
+  return postSession(token, "saved.delete", savedIds(ref), cookie);
+}
+
 // Draft API (internal — requires xoxc session token + xoxd cookie)
 export async function listDrafts(token: string, cookie?: string): Promise<Json> {
   return postSession(token, "drafts.list", {}, cookie);

package/ts/slackTodos.ts

@@ -1,4 +1,4 @@
-// Slack's To-dos tab (app.slack.com/client/<team>/to-dos) — read-only helpers.
+// Slack's To-dos tab (app.slack.com/client/<team>/to-dos) — parsing helpers.
 //
 // Not to be confused with `slack todo` (todo.ts), which tracks tasks as
 // reactions on messages. To-dos are Slack's own PERSONAL list: it replaced
@@ -26,7 +26,7 @@ export type TodoItem = {
   due: number;
   /** Epoch seconds; 0 = not completed. */
   completed: number;
-  /** "to_do" | "saved" (as Slack reports it). */
+  /** "to_do" | "saved" | "completed" (as Slack reports it). */
   todoState: string;
   state: string;
   archived: boolean;
@@ -68,7 +68,8 @@ export function sortTodos(items: TodoItem[]): TodoItem[] {
 }
 
 export function isDone(t: TodoItem): boolean {
-  return t.completed > 0 || t.state === "completed";
+  // Checking one off sets state AND todo_state to "completed" (seen live).
+  return t.completed > 0 || t.state === "completed" || t.todoState === "completed";
 }
 
 /** The status column: a checkbox, plus the due date (and OVERDUE when past it). */

package/ts/stream.ts

@@ -733,7 +733,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
       if (bus.live === live) return;
       bus.live = live;
       _internals.err(live
-        ? `slack stream: relay connected — polling every ${Math.round(Math.max(opts.intervalMs, relay!.reconcileMs) / 1000)}s as a safety net`
+        ? `slack stream: relay connected${why ? ` (${why})` : ""} — polling every ${Math.round(Math.max(opts.intervalMs, relay!.reconcileMs) / 1000)}s as a safety net`
         : `slack stream: relay unavailable${why ? ` (${why})` : ""} — polling every ${Math.round(opts.intervalMs / 1000)}s`);
       ring();
     };
@@ -777,7 +777,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
                 for (const p of [...bus.queue, ...bus.retry, ...(bus.inflight ? [bus.inflight] : [])]) p.seq = Math.min(p.seq, h.seq);
               }
               after = { seq: h.seq, ...(h.epoch ? { epoch: h.epoch } : {}) };
-              setLive(true);
+              setLive(true, h.via);
             },
             bell: (seq, bell) => {
               if (paused) return;