pi-quiver 5.4.0 → 5.5.0

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.
 
+## v5.5.0 - 2026-09-10
+
+- doc_to_md: rewrite primary-PDF image links correctly on Windows.
+- slack: optionally resolve the user token through a credential command on every user-identity tool call, with a configurable timeout in seconds, allowing running pi sessions to use replaced credentials without leaking secrets on command failure or falling back to stale env tokens.
+
 ## v5.4.0 - 2026-09-10
 
 - Settings: one condensed `pi-quiver settings` warning (each distinct message

package/README.md

@@ -274,11 +274,13 @@ Operational notes:
 | --- | --- | --- |
 | `enabled` | `false` | Master switch, checked at `session_start`; toggling takes effect next session. |
 | `cachePath` | user-scope per-OS cache dir | Overrides where the workspace-keyed channel/user name->ID cache file is written; relative paths resolve against the repo root. |
-| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token when `userTokenCommand` is unset (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenCommand` | unset | Executable argv array that prints the current user token to stdout; resolved on every user-identity tool call. |
+| `userTokenCommandTimeoutSeconds` | `10` | Positive finite timeout in seconds for `userTokenCommand`. Increase this when an interactive credential helper may need authorization. |
 | `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. Tokens themselves are resolved per call: process env first, then the repo's `.env` file (or the primary checkout's, for a worktree with none) - never a fallback across identities. 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 and then `.env` (or the primary checkout's, for a worktree with none). 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).
 
 ### doc_to_md settings
 

package/extensions/slack.ts

@@ -19,6 +19,7 @@ import {
 	buildPolicyBlock,
 	discoverRepoRoot,
 	resolveSlackConfig,
+	resolveCredential,
 	resolveToken,
 	searchMessages,
 	readThread,
@@ -40,7 +41,7 @@ import {
 import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
 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 token env var is used and whose name shows as the author.',
+	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.',
 });
 
 // Approved recovery fields only - never dump the raw Slack API response (err.data can carry it
@@ -75,12 +76,13 @@ async function resolveCall(
 	signal: AbortSignal | undefined,
 	repoRoot: string,
 ): Promise<ResolvedCall> {
-	const token = resolveToken(identity, cfg, process.env, repoRoot);
+	const token = await resolveCredential(identity, cfg, process.env, repoRoot);
 	const teamId = await teamIdFor(token, defaultApiCall, signal);
 	const otherIdentity = identity === "user" ? "bot" : "user";
 	const otherTeamId = await (async () => {
+		if (otherIdentity === "user" && cfg.userTokenCommand) return undefined;
 		try {
-			const otherToken = resolveToken(otherIdentity, cfg, process.env, repoRoot);
+			const otherToken = await resolveCredential(otherIdentity, cfg, process.env, repoRoot);
 			return await teamIdFor(otherToken, defaultApiCall, signal);
 		} catch {
 			// Other identity's token can't be resolved/authenticated - best-effort
@@ -99,14 +101,14 @@ async function resolveCall(
 
 /**
  * slack_cache_refresh's identity pick: user token when present, else bot (spec "Cache" section).
- * Pure and network-free - resolveToken only reads env/.env - so it's unit-testable without a
- * transport seam.
+ * Pure and network-free - command configuration counts as a user credential without executing it.
  */
 export function pickCacheRefreshIdentity(
 	cfg: SlackConfig,
 	env: Record<string, string | undefined>,
 	repoRoot: string,
 ): "user" | "bot" {
+	if (cfg.userTokenCommand) return "user";
 	try {
 		resolveToken("user", cfg, env, repoRoot);
 		return "user";

package/lib/extension-config.ts

@@ -47,7 +47,7 @@ export const QUIVER_CONFIG_KEYS: Record<string, readonly string[]> = {
 	sessionAutoName: ["enabled", "ghosttyTab", "herdrTab", "rules", "deny", "revisitFirstTurn", "revisitEveryTurns"],
 	swordHeader: ["enabled"],
 	providerStallWatchdog: ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"],
-	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "botTokenEnv", "uploadThresholdChars"],
+	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "userTokenCommand", "userTokenCommandTimeoutSeconds", "botTokenEnv", "uploadThresholdChars"],
 	docToMd: DOC_TO_MD_OPTIONS.filter((o) => o.settable).map((o) => o.key),
 };
 
@@ -104,7 +104,7 @@ export function resolveConfig<T extends object>(
 	cwd: string,
 	key: string,
 	defaults: T,
-	coerce: (raw: unknown) => Partial<T> | undefined,
+	coerce: (raw: unknown, warn?: (message: string) => void) => Partial<T> | undefined,
 	warn?: (message: string) => void,
 ): T {
 	const cfg: T = { ...defaults };
@@ -119,7 +119,7 @@ export function resolveConfig<T extends object>(
 		const hasFlat = Object.hasOwn(settings, key);
 		if (!hasNested && !(hasFlat && LEGACY_FLAT_KEYS.has(key))) continue;
 		const candidate = hasNested ? nested![key] : settings[key];
-		const patch = coerce(candidate);
+		const patch = coerce(candidate, (message) => emitWarning(warn, message));
 		if (patch) Object.assign(cfg, patch);
 		else emitWarning(warn, `pi-quiver: "${key}" in ${path} has an unrecognized value; ignored.`);
 	}

package/lib/slack-core.ts

@@ -9,7 +9,7 @@
  * slack-local `PI_QUIVER_SLACK_*` env-var overlay applied on top.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -21,6 +21,8 @@ export interface SlackConfig {
 	cachePath: string | undefined;
 	policyPath: string | undefined;
 	userTokenEnv: string;
+	userTokenCommand: string[] | undefined;
+	userTokenCommandTimeoutSeconds: number;
 	botTokenEnv: string;
 	uploadThresholdChars: number;
 }
@@ -30,6 +32,8 @@ export const DEFAULT_SLACK_CONFIG: SlackConfig = {
 	cachePath: undefined,
 	policyPath: undefined,
 	userTokenEnv: "SLACK_USER_TOKEN",
+	userTokenCommand: undefined,
+	userTokenCommandTimeoutSeconds: 10,
 	botTokenEnv: "SLACK_BOT_TOKEN",
 	uploadThresholdChars: 4000,
 };
@@ -44,7 +48,9 @@ export class SlackError extends Error {
 	}
 }
 
-export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
+const MAX_TIMER_SECONDS = 2_147_483.647;
+
+export function coerce(raw: unknown, warn?: (message: string) => void): Partial<SlackConfig> | undefined {
 	if (typeof raw === "boolean") return { enabled: raw };
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const o = raw as Record<string, unknown>;
@@ -53,6 +59,28 @@ export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
 	if (typeof o.cachePath === "string") patch.cachePath = o.cachePath;
 	if (typeof o.policyPath === "string") patch.policyPath = o.policyPath;
 	if (typeof o.userTokenEnv === "string") patch.userTokenEnv = o.userTokenEnv;
+	if (
+		Array.isArray(o.userTokenCommand) &&
+		typeof o.userTokenCommand[0] === "string" &&
+		o.userTokenCommand[0].length > 0 &&
+		o.userTokenCommand.every((part) => typeof part === "string")
+	) {
+		patch.userTokenCommand = [...o.userTokenCommand];
+	}
+	if (o.userTokenCommandTimeoutSeconds !== undefined) {
+		if (
+			typeof o.userTokenCommandTimeoutSeconds === "number" &&
+			Number.isFinite(o.userTokenCommandTimeoutSeconds) &&
+			o.userTokenCommandTimeoutSeconds > 0 &&
+			o.userTokenCommandTimeoutSeconds <= MAX_TIMER_SECONDS
+		) {
+			patch.userTokenCommandTimeoutSeconds = o.userTokenCommandTimeoutSeconds;
+		} else {
+			warn?.(
+				`pi-quiver: quiver.slack.userTokenCommandTimeoutSeconds must be a positive finite number no greater than ${MAX_TIMER_SECONDS}; ignored.`,
+			);
+		}
+	}
 	if (typeof o.botTokenEnv === "string") patch.botTokenEnv = o.botTokenEnv;
 	if (typeof o.uploadThresholdChars === "number" && Number.isInteger(o.uploadThresholdChars) && o.uploadThresholdChars > 0) {
 		patch.uploadThresholdChars = o.uploadThresholdChars;
@@ -222,6 +250,42 @@ export function resolveToken(
 	);
 }
 
+function runCredentialCommand(command: string[], timeoutMs: number): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const [file, ...args] = command;
+		execFile(file, args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 64 * 1024, encoding: "utf8" }, (err, stdout) => {
+			if (err) {
+				const childError = err as NodeJS.ErrnoException & { killed?: boolean; signal?: string | null };
+				if (childError.killed) {
+					reject(new SlackError("credential_command_failed", `Slack user credential command timed out after ${timeoutMs}ms.`));
+					return;
+				}
+				const status = typeof childError.code === "number" ? ` (status ${childError.code})` : "";
+				reject(new SlackError("credential_command_failed", `Slack user credential command failed${status}.`));
+				return;
+			}
+			const token = stdout.trim();
+			if (!token) {
+				reject(new SlackError("missing_token", "Slack user credential command returned no token."));
+				return;
+			}
+			resolve(token);
+		});
+	});
+}
+
+export async function resolveCredential(
+	identity: "user" | "bot",
+	cfg: SlackConfig,
+	env: Record<string, string | undefined>,
+	repoRoot: string,
+): Promise<string> {
+	if (identity === "user" && cfg.userTokenCommand) {
+		return runCredentialCommand(cfg.userTokenCommand, Math.ceil(cfg.userTokenCommandTimeoutSeconds * 1000));
+	}
+	return resolveToken(identity, cfg, env, repoRoot);
+}
+
 /**
  * Data-plane transport: every Slack API call and file upload funnels through
  * these two injectable functions so tests script responses without network.

package/package.json

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

package/scripts/doc_to_md.py

@@ -21,6 +21,12 @@ HTML_IMAGE_RE = re.compile(
 )
 
 
+def image_source_map(source, target, filename):
+    real = os.path.realpath(source)
+    return {source: target, source.replace("\\", "/"): target,
+            real: target, real.replace("\\", "/"): target, filename: target}
+
+
 def rewrite_image_destinations(md, sources):
     def markdown(match):
         dest = match.group(2) if match.group(2) is not None else match.group(3)
@@ -106,7 +112,7 @@ def mode_pdf_primary(o):
                     dest = f"img{i}{os.path.splitext(f)[1].lower()}"
                     source = os.path.join(tmp, f)
                     target = f"p{n}/{dest}"
-                    sources.update({source: target, os.path.realpath(source): target, f: target})
+                    sources.update(image_source_map(source, target, f))
                     os.replace(source, os.path.join(d, dest))
                 md = rewrite_image_destinations(md, sources)
             if not md.strip():