opencode-feishu-plugin 0.1.0 → 0.1.2

package/README.en.md

@@ -21,6 +21,7 @@ Bring [OpenCode](https://opencode.ai) into Feishu/Lark: **one Feishu topic = one
 | ✅ **In-card approvals** | Permission requests become Feishu cards (allow once / always / reject) with signed, replay-proof buttons |
 | 🪜 **Permission presets** | Read-only / Editable / Ask-on-risky / Trust — pick once per session instead of approving every call |
 | 📊 **Live visibility** | Instant ack card, live tool calls (auto-collapsed when ≥3), streaming text, current model in the footer |
+| 🚦 **Status at a glance** | The topic root card changes colour by session state (running/review/pending/done…) with a body footer; the title stays stable and the summary is preserved |
 | 🧵 **Native queueing** | Busy session → messages queue via OpenCode's native `delivery:"queue"` |
 | ⏹ **One-tap force stop** | **Every AI reply card carries a "force stop" button** — one tap interrupts (whitelist + HMAC signed). The watchdog auto-interrupts stuck sessions instead of queueing forever |
 | 🚫 **No ports** | Everything over a long connection; nothing to expose |
@@ -135,7 +136,7 @@ The main chat is management-only; plain text never enters a session.
 | `/form [title]` | Same as `/new` — an equivalent entry point |
 | `/sessions` (`/ls`) | **All** sessions card: each row shows title / short id / relative time / `💬 topic-bound` / `📍 directory`, with a "▶️ Enter topic" button; 8 per page (`sessionPageSize`, 5–20) |
 | `/use <n\|id-prefix>` | Switch current session (legacy, kept for compatibility) |
-| `/resume [n]` | **Resume a past session**: enter the most-recently-updated (or the N-th) session by opening a topic |
+| `/resume [n]` | **Resume a past session**: post a "🔄 resume card" in the main chat for the most-recently-updated (or the N-th) session; **reply to that card** to continue |
 | `/current` | Show current session |
 | `/stop` | Interrupt the running task in the current session (every run card also has a "⏹ force stop" button) |
 | `/steer <text>` | Send a message that **cuts in immediately** (steers into the running step instead of queuing) |
@@ -246,15 +247,22 @@ Besides sessions created from Feishu, you can **load any past OpenCode session v
 - **Paging**: 8 per page by default (`sessionPageSize`, clamped 5–20); the bottom buttons flip pages (`{cmd:"list", page:N}`).
 - **"➕ New session"** opens the setup form card (same as `/new` `/form`) instead of creating a session directly.
 
-**"▶️ Enter topic" — wire a past session into a topic**
+**"▶️ Enter topic" — post a resume card in the main chat**
 
 - Tap the button (value `{cmd:"open", s, c}`): first the session is checked for existence (`ctx.session.get`); if missing → toast "session not found" and the list card is patched into a notice.
-- If it exists → `reply_in_thread` on **the list card message you tapped** posts a "✅ Entered session" card; once `thread_id` is obtained the topic ↔ session mapping (plus the topic root) is bound. **Messages you send in that topic then continue this past session** (OpenCode session context is persistent, so this is effectively a resume).
+- If it exists → a plain resume card is posted in the **main chat**: **title `🔄 <session title>`**, body contains session id / directory / model / last activity / summary, and **that card message** is recorded as the session's root (`root → session`). **No topic is opened and no `thread_id` is bound at this stage.**
+- **How to continue**: simply **reply to the resume card** (Feishu forms a topic under it) to continue that past session. The user's first reply event **may carry only a `root_id` and no `thread_id`**; the plugin falls back to the `root → session` mapping to route to the session, and once a `thread_id` is available it writes the `thread → session` mapping. Later messages in that topic follow normal topic routing. (OpenCode session context is persistent, so this is effectively a resume.)
+- **Summary block (task B, three paths)**:
+  1. **Reuse (zero model calls)**: read the session's **full messages** (`session.message.list`, i.e. `/api/session/{id}/message`; note `/context` is a reduced shape without `summary`) and take the latest `status:"completed"` compaction `summary`, labelled "会话摘要";
+  2. **Fast summary (default path)**: when no native summary exists, it **never feeds the whole session** — it takes the most recent messages, builds a **compact transcript** (per-message clipping, ≤6K chars total) and passes it to a one-shot generation labelled "摘要（快摘要）". That request **must carry `x-opencode-session`**, otherwise the opencode-go endpoint rejects it (`Request is missing x-opencode-session`). It is implemented **A first, B fallback**: A calls `ctx.generate.text(input, { headers: { "x-opencode-session": sessionID } })`; B calls the local HTTP `POST /api/experimental/generate` (Basic auth from `service.json` + URL-encoded `x-opencode-directory`) and sets the header explicitly. It **never** falls back to `ctx.session.generate` (that feeds the whole session and always times out on large sessions). Timeout (`resumeSummaryTimeoutMs`, default **15s**, clamped 3–60s) degrades to "(summary generation failed; just send a message to continue)";
+  3. **Native compaction (user-initiated only)**: the card carries a **"🗜 压缩并总结"** button (value `{cmd:"compact", s, t}`, self-signed token + allowlist + replay guard). Tapping it returns a toast within 3s and **asynchronously** calls `POST /api/session/{id}/compact`; the card shows "🗜 正在压缩会话…" and polls the session messages every 2s until a **new** completed summary appears, then patches to "已压缩 · 会话摘要"; failure/timeout (`resumeCompactTimeoutMs`, default **120s**, clamped 30–300s) only patches an explanation, so you can keep working. **Compaction rewrites session history, so the plugin never triggers it implicitly when entering a session.**
+  Set `resumeSummary: false` to disable the whole summary block and the compact button.
+- Only the clicked session is affected: the card binds just that session's root; other sessions' mappings are untouched.
 - For an already topic-bound session the button becomes "▶️ New topic" — **one session can be routed from several topics** (each topic has its own conversation context; replies land in the triggering topic).
 
 **`/resume [n]` — skip the list**
 
-- `/resume` runs the same "enter topic" flow for the **most recently updated** session; `/resume 3` picks the 3rd row. An out-of-range index reports the valid range.
+- `/resume` runs the same "post a resume card" flow for the **most recently updated** session; `/resume 3` picks the 3rd row. An out-of-range index reports the valid range. It is the same resume card — **reply to it** to continue.
 - It uses the same ordering as `/sessions` (`time.updated` desc).
 
 **Limitations**
@@ -263,6 +271,43 @@ Besides sessions created from Feishu, you can **load any past OpenCode session v
 - `/sessions` and `/resume` are main-chat commands and are **disabled inside topics** (they tell you to go back); once inside a topic just send plain text.
 - With `threadRouting=false` (fallback mode), entering topics and `/resume` are unsupported.
 
+### Topic root card status (colour + footer)
+
+The topic root card (the `/new` created card / the `/resume` resume card) reflects what the session is doing, so you can tell at a glance which sessions need you:
+
+| Kind | Header colour | Footer | Trigger |
+|---|---|---|---|
+| 🟡 Review | `orange` | `🟡 待审核：<tool>` | an **unanswered** permission request (`permission.asked`; cleared on reply) |
+| 🧠 Running | `blue` | `🧠 运行中 · 12:03` | `execution.started` / `session.status(busy\|retry)`, until a terminal event |
+| ⏳ Pending | `grey` | `⏳ 待回复（排队 2）` | the inbox has **queued, not-yet-delivered** messages (`inbox.enqueued` / `delivered`) |
+| 🔴 Failed | `red` | `🔴 失败` | the most recent terminal state was failure (`execution.failed` / run-card failure) |
+| ⏹ Interrupted | `grey` | `⏹ 已中断` | the most recent terminal state was interruption (`execution.interrupted` / `/stop` / watchdog) |
+| ✅ Done | `green` | `✅ 完成` | idle / `execution.succeeded` / `session.status(idle)` |
+
+**Priority (high → low): Review > Running > Pending > Failed/Interrupted > Done.** "Review" is deliberately ranked above "Running": when the session is blocked on an approval, that is exactly when you need to tap the button.
+
+- **The title carries no status by default**: the topic name shows up in the sidebar, and changing it on every status flip is noisy. Status is expressed only via the **header colour + body footer**; the title stays `🔄 <session topic>` (or `✅ 已创建 · <topic>` for a freshly created session). If you really want the status emoji in the title, set `topicStatusInTitle: true` (e.g. `🟡 已完成 · topic`).
+- **The summary/metadata is never lost**: a root card may carry a session summary plus directory/model metadata, and a status refresh is a **whole-card patch**. The plugin first persists the card's "base content" in the session record (`rootCard`) and, on refresh, re-renders from that base with the shared builder before layering the status on top — so a status change **never wipes the summary**.
+- **Only the session's latest root card is updated**: the target message id is the session's `replyMessageId`. A session without it (non-Feishu) or without base content (old session) is **skipped**; the plugin never fabricates a card.
+- **Throttling and fault tolerance**: the card is patched only when the **kind changes**, at most once per `topicStatusThrottleMs` (default 1s). A failed patch only logs a `warn` (the user may have deleted the card) — it never throws or retries in a storm; after repeated consecutive failures for a session the plugin stops refreshing it and logs why.
+- This is fully independent from the per-message **run card**: a status refresh only touches the topic root card and does not change the run card's streaming behaviour.
+
+Config: `topicStatus` (default `true`; disable to stop refreshing entirely), `topicStatusInTitle` (default `false`), `topicStatusThrottleMs` (default `1000`, clamped 500–10000).
+
+### Card content guard (table over-limit degradation)
+
+A Feishu card supports **at most 5 table components**; beyond that `im.message.patch` returns 400 `code=230099 card table number over limit`. The real-world trap: when a single assistant reply contains **many markdown comparison tables** (5+ in one go), **every card patch fails**, the card is stuck on old content, and the user thinks the bot has "frozen".
+
+The plugin guards the **whole card** (not each element separately):
+
+- **Tables are counted cumulatively per card**: multiple markdown elements **share** one budget (default `cardMaxTables=4`, leaving one slot of headroom; clamped 1–5, so even 5 equals the Feishu hard limit).
+- **Tables beyond the budget are degraded into fenced code blocks** (`` ``` `` / `~~~`): **no content is lost**, they are simply no longer rendered as tables, so the 400 is avoided.
+- **A `|` inside a code block is never misdetected as a table**: a per-line fence mask (``` / ~~~, up to 3 leading spaces) is computed first and fenced lines are skipped. Degrading is therefore **idempotent** and never loops.
+- **Element-count backstop**: a single card's component count is clamped to ≤200 (oldest elements are dropped first, keeping the newest content), avoiding another class of 400.
+- Applies to run-card text blocks, topic root / resume cards and their summaries, plus a **final backstop in the send layer** (`sendCard` / `replyCard` / `patchCard`) — no path can emit an over-limit card. A degradation logs a `warn` keyed by `sessionID` (with detected/degraded counts) for observability.
+
+Config: `cardMaxTables` (default `4`, clamped `1–5`).
+
 ### Permission presets
 
 | Preset | Meaning | Session ruleset |
@@ -274,6 +319,20 @@ Besides sessions created from Feishu, you can **load any past OpenCode session v
 
 The preset is written to a **session-scoped** ruleset and can be changed any time with `/perm`, without affecting other sessions.
 
+### Approval card: per-session "allow this tool in this session"
+
+The approval card has **4 buttons** by default: `✅ Allow once` / `🔓 Always allow` / `✅ Allow this tool in this session` / `❌ Reject`.
+
+"Always allow" only persists the **command prefix** OpenCode provides (e.g. `ls *`), so a different command asks again; "Trust" is too broad (it also opens up edit / outside-directory). "**Allow this tool in this session**" is the middle ground:
+
+- It only affects the **current session**: the tool action is recorded in the session's `allowActions` and **appended** to the session ruleset (`{action, resource:"*", effect:"allow"}`); once matched, the `permission.evaluate` gate **no longer downgrades it to ask**, so later calls of the same tool in this session stop bothering you.
+- **Other sessions and the global config are untouched** — switch to another session and it still asks.
+- `shell` and `bash` are allowed together (the real tool id is `bash`, the design name is `shell`; both are covered).
+- Tapping also replies "once" to the **currently pending request** (otherwise this run would still hang), then the card collapses to "✅ Allowed bash in this session" with no buttons.
+- Changing the preset with `/perm` is an explicit permission change: it **clears the session's "allow in this session" grants** so old grants cannot override the new preset.
+- Same security boundary as force-stop: the button value is `{cmd:"allow_session", a:"<action>", t:"<token>"}`; the token reuses the HMAC mechanism and binds `sessionID + action + TTL + nonce` (plus requestID to locate the card). Click validation order is **allow-list → signature → sessionID match → replay guard**; forged / cross-session / replayed taps are rejected, and repeat taps only show a toast.
+- Set `sessionAllowButton: false` to hide this button (the card goes back to three buttons).
+
 ### Queue and cut-in (`/steer` `/now`)
 
 While a session is busy, new messages use OpenCode's native queue (`delivery:"queue"`, the card footer shows "queued") and run only after the current task finishes. Two ways to cut in:
@@ -333,6 +392,14 @@ Without this relay, any clarifying question would stall the Feishu session forev
 | `approvalTtlMs` | number | `600000` | Approval token / card TTL |
 | `staleExecutionMs` | number | `300000` | Watchdog threshold: an execution with no event for this long is treated as stuck and auto-interrupted; a queue stuck this long without `execution.started` also triggers a notice. Clamped to 1–60 minutes |
 | `maxResourcesShown` | number | `8` | Max resource lines shown on an approval card |
+| `sessionAllowButton` | boolean | `true` | Show the "✅ Allow this tool in this session" button on approval cards; disable to go back to three buttons |
+| `resumeSummary` | boolean | `true` | Show a summary on the resume card (reuse a native compaction summary first, else the fast summary; disabling also removes the compact button) |
+| `resumeSummaryTimeoutMs` | number | `15000` | Resume-card **fast summary** timeout (clamped 3000–60000); a timeout is treated as failure and degrades gracefully |
+| `resumeCompactTimeoutMs` | number | `120000` | Poll timeout after a **user-initiated** compaction (`session.compact`), clamped 30000–300000; a timeout only patches an explanation. Compaction is explicit and rewrites session history |
+| `topicStatus` | boolean | `true` | Topic root card status master switch (colour + footer). Disable to stop refreshing entirely |
+| `topicStatusInTitle` | boolean | `false` | Add a status emoji prefix to the root card title (e.g. `🟡 session name`). Off by default: the topic name shows in the sidebar, and flipping it would be noisy |
+| `topicStatusThrottleMs` | number | `1000` | Min root-card status refresh interval (clamped 500–10000); patched only when the kind changes |
+| `cardMaxTables` | number | `4` | Max markdown tables kept per card (clamped 1–5); tables beyond it are degraded **cumulatively per card** into fenced code blocks (no content lost) to avoid Feishu 400 `code=230099` |
 
 ---
 
@@ -343,6 +410,7 @@ permission.evaluate (plugin hook)              permission.asked (event stream)
 ──────────────────────────                     ──────────────────────
 allow-listed tool   → allow                    event carries {id, sessionID, action, resources, save}
 deny list           → deny                                │
+session allowActions → allow (already granted)            │
 otherwise (per session preset) → ask ─────────────────────┘
                                                           ▼
                                       Feishu approval card (button value = signed token)
@@ -357,6 +425,7 @@ otherwise (per session preset) → ask ─────────────
 
 - **Signed tokens**: HMAC-SHA256 binding `requestID + sessionID + operator openId + expiry + nonce`; forgery, forwarding and replay are rejected.
 - **Force-stop uses the same signature scheme**: its token binds `sessionID + purpose + expiry + nonce`, the click passes the open_id allowlist before verification, and it is purpose-isolated from approval tokens (neither works for the other).
+- **Per-session allow uses the same signature scheme**: the approval card's "allow this tool in this session" token binds `sessionID + action + expiry + nonce` (plus requestID to locate the card) and is purpose-isolated. When matched it records `allowActions`, appends a session ruleset, and the `evaluate` gate **no longer downgrades that action to ask** (the `denyTools` red line still wins) — and **only for that session**.
 - **Only Feishu-originated sessions**: sessions without a chat↔session mapping (e.g. your local TUI) are **never downgraded to `ask`**, otherwise they would hang forever with no approval channel.
 - **Three layers of single-user isolation**: platform availability (only you) + no group scopes + code-level open_id allowlist with silent ignore.
 - **`always` semantics**: persisted only when the request carries `save[]`; otherwise it behaves like "once" (the card says so).
@@ -395,7 +464,7 @@ npm test            # vitest (pure logic, no live Feishu)
 npm run dev         # tsup --watch
 ```
 
-**Architecture**: `src/index.ts` wires everything; the Feishu interaction layer lives in `src/feishu/` (event parsing, card builders, topic routing, wizard state machine, streaming-card reducer — mostly **pure functions** for testability); `src/security/` holds token signing and the allowlist.
+**Architecture**: `src/index.ts` is assembly only (config, gateway, watchdog, hook registration and cleanup); `src/runtime/` holds the unit-testable event dispatch (`event-router.ts`) and card-callback routing (`card-action-router.ts`); the session command orchestration is split under `src/session/` (`session-commands.ts` is a thin facade; implementations live in `session-list.ts` / `setup-wizard.ts` / `session-ops.ts` / `model-perm.ts` / `context.ts`); the Feishu interaction layer lives in `src/feishu/` (event parsing, card builders, topic routing, wizard state machine, streaming-card reducer — mostly **pure functions** for testability); `src/security/` holds token signing and the allowlist.
 
 **Implementation notes**
 - Cards are **JSON 2.0** (buttons directly in `body.elements`, callbacks via `behaviors`; the 1.0 `tag:"action"` container returns HTTP 400 on 2.0). Form cards add: `form` must sit at the root of `body.elements`, interactive `name`s must be globally unique, and at least one button must carry `form_action_type:"submit"`.
@@ -417,7 +486,7 @@ This plugin targets **OpenCode V2 only** (`@opencode/plugin`, `Plugin.define`).
 - There is a single main path for creating sessions: the **`/new` / `/form` setup form card**; `/dir` `/model` `/perm` only pre-fill the form. The old directory/model/permissions/confirm step cards are retired from `/new` (their builders and compatibility callbacks remain, marked deprecated).
 - The form is JSON 2.0 (`form` at the root of `body.elements`, globally unique interactive `name`s, a submit button with `form_action_type:"submit"`); some older clients require `select_static` ≥ V3.7.0.
 
-- **A topic's first message may omit `thread_id`**: Feishu sometimes delivers the event without `thread_id` (it is assigned afterwards). If you send a main-chat-only command such as `/new` at that moment, it runs as a main-chat command (e.g. the form card lands in the main chat). Just continue inside the topic with a normal message.
+- **A topic's first message may omit `thread_id`**: Feishu sometimes delivers the event without `thread_id` (it is assigned afterwards). When you **reply to a card that has a root mapping** (e.g. a resume card), the plugin falls back to the `root_id` to route to the corresponding session and writes the topic mapping once a `thread_id` is available. However, for a **brand-new topic** whose event omits `thread_id`, a main-chat-only command such as `/new` sent at that moment runs as a main-chat command (e.g. the form card lands in the main chat). Just continue inside the topic with a normal message.
 
 
 > Publishing tip: `npm publish` triggers `prepublishOnly` (typecheck + build + test). If `node_modules` is missing it **runs `npm ci` first**, so a fresh clone can be published directly without a manual install.