pi-quiver 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v6.2.0 - 2026-09-15
+
+- `slack_thread` flattens Block Kit blocks in its default rendering (blocks joined by ` / `, `[<type>]` for unknown types) and gains an opt-in `raw: true` mode returning thread messages as a pure JSON array for `slack_update` round-trips; both modes go through the existing size gate. (#21)
+
 ## v6.1.0 - 2026-09-15
 
 - `slack`: tokens also resolve from a fixed per-user file - `$XDG_CONFIG_HOME/pi-quiver/.env` or `~/.config/pi-quiver/.env` (Linux/macOS), `%APPDATA%\pi-quiver\.env` (Windows) - after process env, the repo `.env`, and the primary checkout's `.env`. Every rung now falls through when it lacks the key; a repo `.env` holding only the bot token no longer blocks the user token. Breaking: an unreadable `.env` at any rung propagates the raw filesystem error instead of collapsing to `missing_token`; the `missing_token` message now lists every checked path (#22).

package/README.md

@@ -70,7 +70,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
 | `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
 | `extensions/provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
-| `extensions/slack.ts` | `slack_search`, `slack_thread`, `slack_post`, `slack_update`, `slack_delete`, `slack_pin`, `slack_upload`, `slack_cache_refresh` | Context-safe Slack search/threads/posting with dual `user`/`bot` token identities, a workspace-keyed channel/user name->ID cache, DM targets by `@name` / user ID, fetch-style output size gating, and a transactional headline+detail-thread announce protocol with a documented recovery path. OFF by default. Behavior lives in `lib/slack-core.ts` and `lib/slack-cache.ts`. |
+| `extensions/slack.ts` | `slack_search`, `slack_thread`, `slack_post`, `slack_update`, `slack_delete`, `slack_pin`, `slack_upload`, `slack_cache_refresh` | Context-safe Slack search/threads/posting with dual `user`/`bot` token identities, Block Kit flattening and optional raw JSON output for threads, a workspace-keyed channel/user name->ID cache, DM targets by `@name` / user ID, fetch-style output size gating, and a transactional headline+detail-thread announce protocol with a documented recovery path. OFF by default. Behavior lives in `lib/slack-core.ts` and `lib/slack-cache.ts`. |
 
 Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md), [doc/doc-to-md.md](doc/doc-to-md.md), [doc/slack.md](doc/slack.md).
 
@@ -280,7 +280,7 @@ Operational notes:
 | `botTokenEnv` | `SLACK_BOT_TOKEN` | Env var name holding the bot token. |
 | `uploadThresholdChars` | `4000` | Link-collapsed length above which an announce/thread detail body is delivered as a file upload instead of inline text. |
 
-Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env, then the repo `.env`, then the primary checkout's `.env` (linked worktrees), then a per-user `~/.config/pi-quiver/.env` (`$XDG_CONFIG_HOME` / `%APPDATA%` aware); a file lacking the key falls through to the next rung - see [doc/slack.md](doc/slack.md). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
+Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env, then the repo `.env`, then the primary checkout's `.env` (linked worktrees), then a per-user `~/.config/pi-quiver/.env` (`$XDG_CONFIG_HOME` / `%APPDATA%` aware); a file lacking the key falls through to the next rung - see [doc/slack.md](doc/slack.md). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. `slack_thread` flattens Block Kit blocks by default and accepts `raw: true` for JSON output suitable for `slack_update` round-trips. Full reference incl. cache layering, the announce protocol, thread output modes, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
 
 ### doc_to_md settings
 

package/extensions/slack.ts

@@ -161,7 +161,8 @@ export function searchResultText(result: SearchResult): string {
 	return `${result.output}\n\ntotal: ${result.total} | page: ${result.page} of ${result.pageCount}`;
 }
 
-export function threadResultText(result: ThreadResult): string {
+export function threadResultText(result: ThreadResult, raw = false): string {
+	if (raw) return result.output;
 	const lines = [result.output, "", `complete: ${result.complete}`];
 	if (!result.complete && result.nextCursor) lines.push(`next_cursor: ${result.nextCursor}`);
 	if (result.caveat) lines.push(result.caveat);
@@ -269,21 +270,25 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Thread",
 			promptSnippet: "Read all replies in a Slack thread",
 			description:
-				'Read a Slack thread via conversations.replies. Always uses the "user" identity (no `as` param). Provide either `channel` (#name, channel ID, @name, or user ID (DM)) plus `ts`, or a `permalink` (parsed for channel+ts). Paginates by cursor until Slack reports no more replies or a cap of 50 pages / 5,000 messages is hit; the result carries a `complete` flag and a resumable `next_cursor` when capped. Caveat: since 2025-05-29, conversations.replies is rate-limited to ~1 request/minute (limit capped at 15) for apps that are neither Marketplace-listed nor classified internal - hitting that throttle mid-pagination returns the messages collected so far plus a caveat and a resumable cursor instead of spinning. Output is size-gated like slack_search.',
+				'Read a Slack thread via conversations.replies. Always uses the "user" identity (no `as` param). Provide either `channel` (#name, channel ID, @name, or user ID (DM)) plus `ts`, or a `permalink` (parsed for channel+ts). Paginates by cursor until Slack reports no more replies or a cap of 50 pages / 5,000 messages is hit; the result carries a `complete` flag and a resumable `next_cursor` when capped. Caveat: since 2025-05-29, conversations.replies is rate-limited to ~1 request/minute (limit capped at 15) for apps that are neither Marketplace-listed nor classified internal - hitting that throttle mid-pagination returns the messages collected so far plus a caveat and a resumable cursor instead of spinning. Default output is one line per message; messages with Block Kit blocks render those blocks flattened (blocks joined by " / ") instead of the text fallback. `raw: true` is for block extraction and slack_update round-trips: it returns the thread messages as a pure JSON array (no status trailer - `complete`/`next_cursor` stay in the result details and are not visible in the content, so an incomplete raw thread is a partial array with no in-content signal: try JSON.parse, on failure read the file named in the truncation line, and use default mode when completeness matters). Both modes are size-gated like slack_search: over the cap the full output is written to a temp file.',
 			parameters: Type.Object({
 				channel: Type.Optional(Type.String({ description: "#name, channel ID, @name, or user ID (DM)" })),
 				ts: Type.Optional(Type.String({ description: "Thread parent timestamp" })),
 				permalink: Type.Optional(Type.String({ description: "A Slack message permalink URL to parse channel+ts from" })),
 				cursor: Type.Optional(Type.String({ description: "Resume pagination from a next_cursor returned by a prior capped call" })),
+				raw: Type.Optional(Type.Boolean({ description: "Return thread messages as a JSON array of raw message objects (blocks untouched) instead of compact lines" })),
 			}),
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {
 					const { deps, cacheCtx } = await resolveCall("user", cfg, ctx, signal, repoRoot);
 					const channel =
 						params.permalink === undefined && params.channel !== undefined ? await resolveChannel(params.channel, cacheCtx) : undefined;
-					const result = await readThread({ channel, ts: params.ts, permalink: params.permalink, cursor: params.cursor }, deps);
+					const result = await readThread(
+						{ channel, ts: params.ts, permalink: params.permalink, cursor: params.cursor, raw: params.raw },
+						deps,
+					);
 					return {
-						content: [{ type: "text" as const, text: threadResultText(result) }],
+						content: [{ type: "text" as const, text: threadResultText(result, params.raw === true) }],
 						details: result,
 					};
 				}, "user");

package/lib/slack-core.ts

@@ -567,15 +567,107 @@ export async function searchMessages(
 	return { ...gated, total, page, pageCount };
 }
 
+function inlineElementText(element: unknown): string {
+	if (typeof element !== "object" || element === null) return "[unknown]";
+	const el = element as Record<string, unknown>;
+	const type = typeof el.type === "string" ? el.type : "unknown";
+	switch (type) {
+		case "text":
+			return typeof el.text === "string" ? el.text : "[text]";
+		case "user":
+			return typeof el.user_id === "string" ? `<@${el.user_id}>` : "[user]";
+		case "channel":
+			return typeof el.channel_id === "string" ? `<#${el.channel_id}>` : "[channel]";
+		case "link":
+			if (typeof el.text === "string" && el.text.length > 0) return el.text;
+			return typeof el.url === "string" ? el.url : "[link]";
+		case "emoji":
+			return typeof el.name === "string" ? `:${el.name}:` : "[emoji]";
+		default:
+			return `[${type}]`;
+	}
+}
+
+function richTextContainerText(element: unknown): string {
+	if (typeof element !== "object" || element === null) return "[unknown]";
+	const el = element as Record<string, unknown>;
+	const type = typeof el.type === "string" ? el.type : "unknown";
+	switch (type) {
+		case "rich_text_section":
+		case "rich_text_quote":
+		case "rich_text_preformatted":
+			return Array.isArray(el.elements) ? el.elements.map(inlineElementText).join("") : "";
+		case "rich_text_list":
+			return Array.isArray(el.elements)
+				? el.elements.map(richTextContainerText).filter((s) => s.length > 0).join(" ")
+				: "";
+		default:
+			return `[${type}]`;
+	}
+}
+
+function contextElementText(element: unknown): string {
+	if (typeof element !== "object" || element === null) return "[unknown]";
+	const el = element as Record<string, unknown>;
+	const type = typeof el.type === "string" ? el.type : "unknown";
+	if (type === "plain_text" || type === "mrkdwn") {
+		return typeof el.text === "string" ? el.text : `[${type}]`;
+	}
+	return `[${type}]`;
+}
+
+function blockText(block: unknown): string {
+	if (typeof block !== "object" || block === null) return "[unknown]";
+	const b = block as Record<string, unknown>;
+	const type = typeof b.type === "string" ? b.type : "unknown";
+	switch (type) {
+		case "header": {
+			const text = (b.text as Record<string, unknown> | undefined)?.text;
+			return typeof text === "string" ? text : "";
+		}
+		case "section": {
+			const parts: string[] = [];
+			const text = (b.text as Record<string, unknown> | undefined)?.text;
+			if (typeof text === "string" && text.length > 0) parts.push(text);
+			if (Array.isArray(b.fields)) {
+				for (const field of b.fields) {
+					const fieldText = (field as Record<string, unknown> | undefined)?.text;
+					if (typeof fieldText === "string" && fieldText.length > 0) parts.push(fieldText);
+				}
+			}
+			return parts.join(" ");
+		}
+		case "context":
+			return Array.isArray(b.elements)
+				? b.elements.map(contextElementText).filter((s) => s.length > 0).join(" ")
+				: "";
+		case "rich_text":
+			return Array.isArray(b.elements)
+				? b.elements.map(richTextContainerText).filter((s) => s.length > 0).join(" ")
+				: "";
+		default:
+			return `[${type}]`;
+	}
+}
+
+export function renderBlocks(blocks: unknown[]): string {
+	return blocks
+		.map(blockText)
+		.filter((s) => s.length > 0)
+		.join(" / ")
+		.replace(/\r?\n/g, " ");
+}
+
 function renderThreadLine(message: Record<string, unknown>): string {
 	const author = typeof message.user === "string" ? message.user : String(message.username ?? "unknown");
 	const ts = String(message.ts ?? "");
-	const text = typeof message.text === "string" ? message.text.replace(/\r?\n/g, " ") : "";
-	return `${author} | ${ts} | ${text}`;
+	const flattened = Array.isArray(message.blocks) && message.blocks.length > 0 ? renderBlocks(message.blocks) : "";
+	const body = (flattened.length > 0 ? flattened : typeof message.text === "string" ? message.text : "").replace(/\r?\n/g, " ");
+	return `${author} | ${ts} | ${body}`;
 }
 
 export async function readThread(
-	args: { channel?: string; ts?: string; permalink?: string; cursor?: string },
+	args: { channel?: string; ts?: string; permalink?: string; cursor?: string; raw?: boolean },
 	deps: CoreDeps,
 ): Promise<ThreadResult> {
 	let channel = args.channel;
@@ -641,7 +733,7 @@ export async function readThread(
 		cursor = fetchedCursor;
 	}
 
-	const rendered = messages.map(renderThreadLine).join("\n");
+	const rendered = args.raw === true ? JSON.stringify(messages, null, 2) : messages.map(renderThreadLine).join("\n");
 	const gated = gateOutput(rendered, "thread");
 	return { ...gated, complete, nextCursor, caveat, messageCount: messages.length };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",