pi-quiver 6.7.0 → 6.7.1

package/CHANGELOG.md

@@ -8,6 +8,11 @@ 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.7.1 - 2026-10-01
+
+- `slack_post`/`slack_update` explain native Slack representations for skill-required formatting, with complete readable fallback; otherwise plain content stays plain.
+- `slack_post` announcements carry native blocks in the detail reply without upload fallback and preserve structured detail in JSON for existing-thread recovery.
+
 ## v6.7.0 - 2026-09-30
 
 - README: `swordHeader` note on why pi's built-in logo flashes before the sword appears and how `quietStartup` removes it.

package/extensions/slack.ts

@@ -40,6 +40,19 @@ import {
 } from "../lib/slack-core.ts";
 import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
+const SLACK_FORMATTING_GUIDANCE: { rules: string[]; example: string } = {
+	rules: [
+		"For slack_post and slack_update, represent only formatting required by the calling skill. Keep otherwise plain content plain; preserve required structure rather than flattening it to a prose paragraph.",
+		'For slack_post and slack_update, use required lists as rich_text blocks containing rich_text_list with style: "bullet" or style: "ordered" and rich_text_section items. Preserve order and item boundaries; use line-separated text markers only in fallback, not as a substitute for the native list.',
+		"For slack_post and slack_update, represent required block quotations with rich_text_quote inside rich_text. Preserve quoted wording and supplied attribution. In text-only fallback, put > at the start of quoted lines and distinguish quotation from commentary; retain the required native quotation.",
+		"For slack_post and slack_update, inside rich_text represent required emphasis with text-element style properties bold, italic, strike; use code style for inline code, rich_text_preformatted for multiline code, and native link elements for labeled links. Keep mrkdwn delimiters out of native text leaves. On text-only surfaces, use *bold*, _italic_, ~strike~, backticks for inline code, triple-backticks for multiline code, and <url|label> for labeled links; code alone does not introduce blocks.",
+		"For slack_post and slack_update, preserve literal code. In text-only code and fallback, supply \\@name for literal mention-like names, including echo \\@alice for literal echo @alice; backticks do not suppress mention scanning. Rely on name lookup only in text and thread_body; treat @name in blocks as literal.",
+		"For slack_post and slack_update, when authoring blocks also supply complete readable fallback with substantive content, list item boundaries, and quotation/commentary distinctions for notifications and screen readers. Pair blocks with text for ordinary posts and updates, with thread_body ?? text for existing-thread replies, and with thread_body for announcement detail without thread_ts. Keep the announcement text headline text-only; blocks belong only to its detail. Without thread_body, blocks do not create an announcement. Pass caller-authored blocks through for Slack validation; existing blocks-only callers remain supported.",
+		"For slack_post and slack_update, keep blocks-bearing threaded replies and announcement details as messages: they bypass the local MAX_TEXT_LENGTH fallback guard and never use threshold-based or msg_too_long upload fallback.",
+	],
+	example: 'Native list example: {"text":"- First\\n- Second","blocks":[{"type":"rich_text","elements":[{"type":"rich_text_list","style":"bullet","elements":[{"type":"rich_text_section","elements":[{"type":"text","text":"First"}]},{"type":"rich_text_section","elements":[{"type":"text","text":"Second"}]}]}]}]}',
+};
+
 const IDENTITY = Type.Union([Type.Literal("user"), Type.Literal("bot")], {
 	description: 'Which token to act as: "user" (a real person, needed for slack_search/slack_thread) or "bot" (an app identity). Determines which credential source is used and whose name shows as the author.',
 });
@@ -302,14 +315,15 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Post",
 			promptSnippet: "Post a Slack message, reply, or headline+detail announcement",
 			description:
-				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact.",
+				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts the detail `blocks` with `thread_body` fallback (or text-only `thread_body`) as the first threaded reply in the same call; for text-only detail, if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the returned error supplies recovery-artifact details. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact." + "\n\n" + SLACK_FORMATTING_GUIDANCE.rules.join("\n") + "\n\n" + SLACK_FORMATTING_GUIDANCE.example,
+			promptGuidelines: SLACK_FORMATTING_GUIDANCE.rules,
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
-				text: Type.Optional(Type.String({ description: "Message text, or the announce headline when thread_body is set" })),
-				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
+				text: Type.Optional(Type.String({ description: "Message fallback, or text-only announcement headline when thread_body is set without thread_ts" })),
+				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON for the posted body, or detail reply in combined announcements; passed through unvalidated" })),
 				thread_ts: Type.Optional(Type.String({ description: "Reply into this existing thread instead of posting a new headline" })),
-				thread_body: Type.Optional(Type.String({ description: "Detail body for an announce headline, or the reply body when thread_ts is set" })),
+				thread_body: Type.Optional(Type.String({ description: "Detail fallback in announce mode without thread_ts, or reply fallback when thread_ts is set" })),
 				unfurl_links: Type.Optional(
 					Type.Boolean({ description: "Slack unfurls link previews by default; pass false to suppress text-link previews for this message." }),
 				),
@@ -384,13 +398,14 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Update",
 			promptSnippet: "Edit an existing Slack message",
 			description:
-				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).',
+				'Edit a message via chat.update, as `as: "user"` or `as: "bot"`. `channel` accepts #name, channel ID, @name, or user ID (DM). Only the identity that originally posted the message can edit it (Slack constraint; surfaced as an error otherwise). Accepts `text` and/or `blocks` (Block Kit JSON, unvalidated).' + "\n\n" + SLACK_FORMATTING_GUIDANCE.rules.join("\n") + "\n\n" + SLACK_FORMATTING_GUIDANCE.example,
+			promptGuidelines: SLACK_FORMATTING_GUIDANCE.rules,
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name, channel ID, @name, or user ID (DM)" }),
 				ts: Type.String({ description: "Timestamp of the message to edit" }),
-				text: Type.Optional(Type.String()),
-				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
+				text: Type.Optional(Type.String({ description: "Readable message fallback with blocks, or text-only message body" })),
+				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON for the edited message body, passed through unvalidated" })),
 			}),
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {

package/lib/slack-core.ts

@@ -800,7 +800,7 @@ export async function postPlain(
 	},
 	deps: CoreDeps,
 ): Promise<MutationResult> {
-	assertTextWithinLimit(args.text);
+	if (!(args.blocks && args.thread_ts !== undefined)) assertTextWithinLimit(args.text);
 
 	const params: Record<string, unknown> = { channel: args.channel };
 	if (args.text !== undefined) params.text = args.text;
@@ -947,13 +947,13 @@ export function formatUnresolvedSuffix(
 	return suffix;
 }
 
-export function persistDetail(body: string): string {
+export function persistDetail(body: string, format: "md" | "json" = "md"): string {
 	const dir = join(tmpdir(), "pi-slack");
 	mkdirSync(dir, { recursive: true });
 	const hash = createHash("sha256").update(body).digest("hex").slice(0, 8);
 	// Same-millisecond re-invocation with identical content hashes to the same filename and
 	// overwrites with byte-identical bytes - harmless, so no collision handling is needed here.
-	const path = join(dir, `${Date.now()}-${hash}-detail.md`);
+	const path = join(dir, `${Date.now()}-${hash}-detail.${format}`);
 	writeFileSync(path, body, "utf8");
 	return path;
 }
@@ -1007,7 +1007,7 @@ async function deliverDetailUploadOrPersist(
 	channel: string,
 	threadTs: string,
 	body: string,
-	deps: CoreDeps & { uploadBytes: UploadBytes; persist?: (body: string) => string },
+	deps: CoreDeps & { uploadBytes: UploadBytes; persist?: (body: string, format?: "md" | "json") => string },
 ): Promise<{ detailTs?: string }> {
 	try {
 		return await deliverDetailUpload(channel, threadTs, body, deps);
@@ -1028,14 +1028,22 @@ async function deliverDetailUploadOrPersist(
  * also failed and the (now unrecoverable) detail body's length, and omit detailPath from the
  * caller's structured error data.
  */
-function persistOrDescribe(body: string, persist: (body: string) => string): { detailPath?: string; note: string } {
+function persistOrDescribe(
+	body: string,
+	persist: (body: string, format?: "md" | "json") => string,
+	format: "md" | "json" = "md",
+	knownHeadline = true,
+): { detailPath?: string; note: string } {
 	try {
-		const detailPath = persist(body);
-		return { detailPath, note: `the full detail was saved to ${detailPath}` };
+		const detailPath = persist(body, format);
+		const recovery = format === "json"
+			? `${knownHeadline ? "; recover with saved text as thread_body and saved blocks using the known thread_ts" : "; locate the headline in the channel and obtain its ts before recovering with saved text as thread_body and saved blocks using that thread_ts"}; correct rejected blocks before recovery, preserving the original artifact`
+			: "";
+		return { detailPath, note: `the full detail was saved to ${detailPath}${format === "json" ? " (json)" : ""}${recovery}` };
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		return {
-			note: `persisting the ${body.length}-char detail body ALSO failed (${msg}) - the detail is unrecoverable`,
+			note: `persisting the ${body.length}-char detail ${format === "json" ? "payload" : "body"} ALSO failed (${msg}) - the detail is unrecoverable`,
 		};
 	}
 }
@@ -1055,9 +1063,10 @@ async function recoverFromDetailFailure(
 	ts: string,
 	permalink: string | undefined,
 	deps: CoreDeps,
-	persist: (body: string) => string,
+	persist: (body: string, format?: "md" | "json") => string,
+	format: "md" | "json" = "md",
 ): Promise<never> {
-	const { detailPath, note } = persistOrDescribe(detailBody, persist);
+	const { detailPath, note } = persistOrDescribe(detailBody, persist, format);
 
 	let markerFailureMessage: string | undefined;
 	try {
@@ -1085,17 +1094,19 @@ async function recoverFromDetailFailure(
 }
 
 export async function announce(
-	args: { channel: string; text: string; thread_body: string },
+	args: { channel: string; text: string; thread_body: string; blocks?: unknown[] },
 	deps: CoreDeps & {
 		uploadBytes: UploadBytes;
 		thresholdChars: number;
-		persist?: (body: string) => string;
+		persist?: (body: string, format?: "md" | "json") => string;
 		unfurl_links?: boolean;
 		unfurl_media?: boolean;
 	},
 ): Promise<AnnounceResult> {
 	assertHeadline(args.text);
 	const persist = deps.persist ?? persistDetail;
+	const detailFormat = args.blocks ? "json" : "md";
+	const detailBody = args.blocks ? JSON.stringify({ text: args.thread_body, blocks: args.blocks }) : args.thread_body;
 	const unfurl: Record<string, unknown> = {};
 	if (deps.unfurl_links !== undefined) unfurl.unfurl_links = deps.unfurl_links;
 	if (deps.unfurl_media !== undefined) unfurl.unfurl_media = deps.unfurl_media;
@@ -1105,7 +1116,7 @@ export async function announce(
 		headlineData = await deps.apiCall("chat.postMessage", deps.token, { channel: args.channel, text: args.text, ...unfurl }, { retry: false, signal: deps.signal });
 	} catch (err) {
 		if (err instanceof SlackError && err.code === "transport") {
-			const { detailPath, note } = persistOrDescribe(args.thread_body, persist);
+			const { detailPath, note } = persistOrDescribe(detailBody, persist, detailFormat, false);
 			throw new SlackError(
 				"outcome_unknown",
 				`Headline post to ${args.channel} may or may not have reached Slack (${err.message}); check the channel before re-invoking slack_post. ${capitalize(note)}.`,
@@ -1125,24 +1136,24 @@ export async function announce(
 	try {
 		ts = requireResponseString(headlineData, "chat.postMessage", "ts");
 	} catch (err) {
-		const { detailPath, note } = persistOrDescribe(args.thread_body, persist);
+		const { detailPath, note } = persistOrDescribe(detailBody, persist, detailFormat, false);
 		const detail = err instanceof Error ? err.message : String(err);
 		throw new SlackError(
 			"outcome_unknown",
-			`Headline post to ${channel} WAS accepted by Slack (ok:true) but the response was unparseable (${detail}); do NOT re-invoke slack_post - thread the detail manually. ${capitalize(note)}.`,
+			`Headline post to ${channel} WAS accepted by Slack (ok:true) but the response was unparseable (${detail}); ${args.blocks ? "do NOT repost the headline - recover only into its thread" : "do NOT re-invoke slack_post - thread the detail manually"}. ${capitalize(note)}.`,
 			{ channel, ...(detailPath ? { detailPath } : {}) },
 		);
 	}
 
 	const { permalink, warning } = await withPermalink(deps, channel, ts);
 
-	if (linkCollapsedLength(args.thread_body) > deps.thresholdChars) {
+	if (!args.blocks && linkCollapsedLength(args.thread_body) > deps.thresholdChars) {
 		let detailTs: string | undefined;
 		try {
 			({ detailTs } = await deliverDetailUpload(channel, ts, args.thread_body, deps));
 		} catch (err) {
 			const causeMessage = err instanceof Error ? err.message : String(err);
-			return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+			return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 		}
 		return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 	}
@@ -1152,21 +1163,21 @@ export async function announce(
 		detailData = await deps.apiCall(
 			"chat.postMessage",
 			deps.token,
-			{ channel, text: args.thread_body, thread_ts: ts, ...unfurl },
+			{ channel, text: args.thread_body, thread_ts: ts, ...(args.blocks ? { blocks: args.blocks } : {}), ...unfurl },
 			{ retry: true, signal: deps.signal },
 		);
 	} catch (err) {
-		if (err instanceof SlackError && err.code === "msg_too_long") {
+		if (!args.blocks && err instanceof SlackError && err.code === "msg_too_long") {
 			try {
 				const { detailTs } = await deliverDetailUpload(channel, ts, args.thread_body, deps);
 				return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 			} catch (uploadErr) {
 				const causeMessage = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
-				return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+				return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 			}
 		}
-		const causeMessage = err instanceof Error ? err.message : String(err);
-		return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
+		const causeMessage = args.blocks && err instanceof SlackError && !err.message.startsWith(`${err.code}:`) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+		return recoverFromDetailFailure(causeMessage, args.text, detailBody, channel, ts, permalink, deps, persist, detailFormat);
 	}
 
 	const detailTs = requireResponseString(detailData, "chat.postMessage", "ts");
@@ -1183,11 +1194,11 @@ export async function postMessage(
 		unfurl_links?: boolean;
 		unfurl_media?: boolean;
 	},
-	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => string },
+	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string, format?: "md" | "json") => string },
 ): Promise<MutationResult | AnnounceResult> {
 	if (args.thread_body !== undefined && args.thread_ts === undefined) {
 		return announce(
-			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body },
+			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body, blocks: args.blocks },
 			{ ...deps, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
 		);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "6.7.0",
+  "version": "6.7.1",
   "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",