pi-quiver 4.4.0 → 5.0.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ 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.0.0 - 2026-08-29
+
+- **New opt-in `slack` extension** (#7): eight `slack_*` tools (search, thread, post, update, delete, pin, upload, cache refresh) for context-safe Slack search/threads/posting. Dual `user`/`bot` token identities resolved per call from process env or the repo's `.env`, never cross-identity fallback. Workspace-keyed channel/user name->ID cache with a repo-overridable `cachePath`. Fetch-style output size gating on search/thread reads. `slack_post`'s `thread_body` (no `thread_ts`) posts a transactional headline+thread announce - oversized detail bodies upload as a file - with a documented recovery path on delivery failure. OFF by default; nested-only `quiver.slack` config, no legacy flat form. See [doc/slack.md](doc/slack.md).
+
+## v4.5.0 - 2026-08-29
+
+- Settings resolution: every pi-quiver setting is now read from an optional `"quiver"` root object in `settings.json` (`quiver.<key>`), grouping the four legacy flat keys (`fastMode`, `sessionAutoName`, `swordHeader`, `providerStallWatchdog`) plus any future key. The flat top-level form keeps working, but only for those four legacy keys - it is frozen there and never extended to new settings. Within a layer, `quiver.<key>` wins over flat `<key>` by presence; malformed values and flat/nested duplicates now emit a warning instead of resolving silently.
+
 ## v4.4.0 - 2026-08-26
 
 - doc_to_md: backend ladder now tries a system Python >= 3.12 with `pymupdf4llm` importable, then a one-time managed venv (bootstrapped at the version pin into a per-OS cache dir) between the existing `uv` and `unpdf` rungs. Data plane extracted to pi-free `lib/doc-to-md-core.ts`; new `pi-quiver doc-to-md <path>` CLI subcommand and `doc-to-md` Claude Code skill. `uv`/`soffice` detection is now spawn-based (Windows-correct). The bundled Python conversion script is now resolved from the package root, fixing a path bug that broke it under the bundled CLI.

package/README.md

@@ -18,7 +18,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 `fetch` and `doc_to_md` bring real web pages, GitHub issues/PRs, and local PDF/DOCX/PPTX files into context - and every result is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint, so a single call can never flood the window. Ingestion is what makes data-driven work possible; the gate is what keeps it safe.
 
-`session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in ergonomics and recovery controls: session labeling, a themed startup header, Anthropic fast mode, and semantic-stall recovery.
+`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting.
 
 ## Part of the pi agent toolkit
 
@@ -33,7 +33,7 @@ No code dependency between them. pi-quiver is call-level: it gates the size of w
 
 ## Mental model
 
-Every ingestion extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. `fetch` and `doc_to_md` bring real sources in; `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in.
+Every ingestion extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. `fetch` and `doc_to_md` bring real sources in; `session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in.
 
 ```mermaid
 flowchart LR
@@ -68,8 +68,9 @@ 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, 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).
+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).
 
 ## Key concepts
 
@@ -78,7 +79,7 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 | Size gate | Text/Markdown/JSON output over 32 KB or 1000 lines spills to a temp file with a 60-line preview instead of inlining. |
 | Content routing | HTML -> Markdown, binary -> untouched file, GitHub URLs -> `gh` CLI (failed runs/jobs get failed-step logs appended), everything else -> the size gate. |
 | Graceful degradation | Optional binaries (`gh`, `uv`, LibreOffice) are never hard install-time deps; each has a defined, documented fallback or failure mode. |
-| Opt-in extensions | `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` do nothing until explicitly enabled in `settings.json`. |
+| Opt-in extensions | `session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` do nothing until explicitly enabled in `settings.json`. |
 | Provider stall recovery | The watchdog detects a missing first stream event and missing parsed semantic progress, not network liveness. The pre-first-event tier covers every mode and origin; the mid-stream tier is TUI-only. |
 
 ## When to use
@@ -137,45 +138,72 @@ None is a hard install-time dependency of the package; they are tools you provid
 
 ### Opt-in extension config
 
-These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
+These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer), nested under an optional `"quiver"` root:
 
 ```jsonc
 {
-  "sessionAutoName": {
-    "enabled": false,
-    "ghosttyTab": true,
-    "rules": [],
-    "deny": [],
-    "revisitFirstTurn": 0,
-    "revisitEveryTurns": 0
-  }, // or boolean shorthand
-  "swordHeader": false, // or { "enabled": true }
-  "fastMode": false,                                           // or { "enabled": true }
-  "providerStallWatchdog": false                               // or { "enabled": true }
+  "quiver": {
+    "sessionAutoName": {
+      "enabled": false,
+      "ghosttyTab": true,
+      "rules": [],
+      "deny": [],
+      "revisitFirstTurn": 0,
+      "revisitEveryTurns": 0
+    }, // or boolean shorthand
+    "swordHeader": false, // or { "enabled": true }
+    "fastMode": false,                                         // or { "enabled": true }
+    "providerStallWatchdog": false,                            // or { "enabled": true }
+    "slack": false                                             // or { "enabled": true, ... }
+  }
 }
 ```
 
+Each key resolves independently: within a layer, `quiver.<key>` wins over a
+flat top-level `<key>` by presence alone (even when the winning value is
+malformed); across layers, each layer's candidate is validated into a partial
+patch and `Object.assign`ed over the accumulator in layer order (project
+last), so project fields override matching global fields while unmatched
+global fields survive - a flat-vs-nested shape difference between layers
+never changes this. The flat top-level form still works, but only for four
+legacy keys, frozen at `fastMode`, `sessionAutoName`, `swordHeader`, and
+`providerStallWatchdog` - never extended to new settings (see [Migrating from
+flat keys](#migrating-from-flat-keys)).
+
+Worked mixed-shape example: global `settings.json` has flat
+`"fastMode": false`, project `.pi/settings.json` has
+`"quiver": { "fastMode": { "enabled": true } }`. The project layer's
+patch (`{ "enabled": true }`) is `Object.assign`ed over the accumulator
+seeded from global's patch, so the resolved config is `{ "enabled": true }` -
+same outcome here because `enabled` is the only field either layer sets, but
+the merge is per-field: a global field with no project counterpart would
+survive untouched.
+
 `sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `rules` appends house conventions to the naming prompt (later rules win when they conflict with the built-ins). Literal, case-insensitive `deny` phrases are stripped from every name; whitespace inside a phrase is loose, so `"acme corp"` also catches `AcmeCorp`. `revisitFirstTurn` re-evaluates the name once that many model round trips have completed, while `revisitEveryTurns` does so at every multiple; both default to `0` (off) because each revisit costs another short LLM call. For example, `10` and `100` mark round trips 10, 100, 200, 300. Revisits only run when the agent has fully settled (idle, nothing queued) - an automated multi-turn run such as a subagent chain is never renamed or delayed mid-flight; cadence points it crossed fire once, at the settle. A machine-generated name is replaced when stale. A name set by a human is never overwritten: the extension strongly prefers it, and announces a suggestion only when the work has clearly moved on. Counts come from the persisted transcript, so they survive resume.
 
 `fastMode` only affects `claude-opus-4-8` and `claude-opus-5` requests on Anthropic's `anthropic-messages` API; enabling it opts into premium fast-mode pricing. `--fast` forces it on for one launch; `/fast on|off` toggles live. Proxy providers (opencode, cloudflare-ai-gateway) are excluded. `fastMode`'s header injection needs the `before_provider_headers` hook (pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5); on older pi the beta header is silently not sent. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
 
 `pi-ai` prices every fast request at standard rates - it has no `usage.speed` support and no request-level pricing modifier - so `fastMode` corrects the reported cost itself: a `message_end` handler scales all four `usage.cost` components by `FAST_MODE_COST_MULTIPLIER` (2x) and returns the corrected message. Persisted session JSONL and pi's own native cost display are always exact, since they're written from this corrected message. pi-cohort's live `Σ$` reflects the correction only when pi-quiver's `message_end` handler runs before pi-cohort's - best-effort, depending on extension load order - and is reconciled on pi-cohort's next `session_start` regardless. The upstream fix (teaching `pi-ai`'s `Usage`/`calculateCost` about `usage.speed`) is the better long-term path and is tracked separately.
 
-Recommended explicit retry and watchdog settings:
+Recommended explicit retry and watchdog settings - `providerStallWatchdog`
+nests under `quiver`, while pi-core's own `retry` stays flat beside it (it is
+not a pi-quiver setting and is never nested):
 
 ```json
 {
+  "quiver": {
+    "providerStallWatchdog": {
+      "enabled": true,
+      "firstEventMs": 20000,
+      "warningMs": 120000,
+      "recoveryMs": 240000,
+      "maxStallRetries": 3
+    }
+  },
   "retry": {
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000
-  },
-  "providerStallWatchdog": {
-    "enabled": true,
-    "firstEventMs": 20000,
-    "warningMs": 120000,
-    "recoveryMs": 240000,
-    "maxStallRetries": 3
   }
 }
 ```
@@ -205,13 +233,63 @@ Operational notes:
 - **A watchdog abort that the provider ignores escalates after a fixed 10s.** Any post-abort stream event re-arms that deadline (bytes prove only that the connection was alive at that instant), so a stream that emits a straggler and then wedges still escalates 10s after its last event. This reduces the hang; it cannot force the provider to stop, and undici's timeouts remain the final backstop.
 - **Headless runs report on stderr.** In `print`/`json` mode pi binds a no-op UI, so watchdog notices go out via `console.warn`. Nothing is ever written to stdout, which `json` mode uses for its protocol. In TUI and RPC the notices render as main-window notifications, not the bottom status line.
 
+`slack` is OFF by default and, once enabled, adds eight `slack_*` tools (search, thread, post, update, delete, pin, upload, cache refresh) covering context-safe Slack search/threads/posting under dual `user`/`bot` token identities. Nested-only from day one (no legacy flat form):
+
+```json
+{
+  "quiver": {
+    "slack": {
+      "enabled": true,
+      "cachePath": ".pi/slack-cache.json",
+      "userTokenEnv": "SLACK_USER_TOKEN",
+      "botTokenEnv": "SLACK_BOT_TOKEN",
+      "uploadThresholdChars": 4000
+    }
+  }
+}
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `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). |
+| `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).
+
+### Migrating from flat keys
+
+The flat top-level form (`"fastMode": ...` etc. directly under `settings.json`)
+is the outdated configuration style. It is legacy-frozen to exactly the four
+keys above - `fastMode`, `sessionAutoName`, `swordHeader`,
+`providerStallWatchdog` - and will never gain a fifth. To migrate, wrap your
+existing keys under `"quiver": { ... }` and delete the flat copies:
+
+```jsonc
+// before
+{ "fastMode": true }
+
+// after
+{ "quiver": { "fastMode": true } }
+```
+
+Until you delete the flat copy, having both set is not an error - the
+duplicate resolves per the precedence above (nested wins within a layer) -
+but it emits a warning notification, deduped per process (each unique
+message fires at most once per pi process - in practice once per interactive
+session) until the flat entry is removed. Every new pi-quiver setting introduced after this change
+(for example a future `slack` key) is nested-only from day one: it has no
+flat form to fall back to.
+
 ## Claude Code support
 
 `fetch`'s core (`lib/fetch-core.ts`) is also published as a CLI, so Claude Code can use the same routing, size gate, and spill behavior as pi's native tool - without pi ever seeing Claude-only files.
 
 **Exposed:** the `quiver` plugin, served from this repo's `.claude-plugin/marketplace.json`, with two skills: `fetch` (invoked as `quiver:fetch` / `/quiver:fetch`) and `doc-to-md` (invoked as `quiver:doc-to-md` / `/quiver:doc-to-md`). The `fetch` skill runs `npx -y pi-quiver@latest fetch <url> [flags]` via Bash - full parameter parity with the pi tool (`--method`, `--header`, `--body`, `--raw`, `--timeout-ms`), same GitHub `gh` routing (including failed-step logs on failed runs/jobs), same size gate, same binary-to-temp-file handling. See [doc/fetch.md](doc/fetch.md#claude-code-cli-pi-quiver-fetch) for exit codes and flags. The `doc-to-md` skill runs `npx -y pi-quiver@latest doc-to-md <path>` via Bash - same backend ladder, size gate, and degraded-fallback marking as the pi tool. See [doc/doc-to-md.md](doc/doc-to-md.md#cli-pi-quiver-doc-to-md) for exit codes.
 
-**Not exposed:** the other pi extensions in this package (`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`) - the marketplace allowlists only `./skills/fetch` and `./skills/doc-to-md`, and the npm tarball never ships `skills/` or `.claude-plugin/` (pi's own `files` allowlist excludes them, and pi's explicit `pi.extensions` manifest makes them invisible to pi's convention-directory auto-discovery either way).
+**Not exposed:** the other pi extensions in this package (`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, `slack`) - the marketplace allowlists only `./skills/fetch` and `./skills/doc-to-md`, and the npm tarball never ships `skills/` or `.claude-plugin/` (pi's own `files` allowlist excludes them, and pi's explicit `pi.extensions` manifest makes them invisible to pi's convention-directory auto-discovery either way).
 
 Add the marketplace and enable the plugin in `.claude/settings.json`:
 

package/extensions/fast-mode.ts

@@ -116,7 +116,7 @@ export default function (pi: ExtensionAPI) {
 	const readFlag = (): boolean => pi.getFlag("fast") === true;
 
 	const resolveState = (ctx: ExtensionContext): boolean => {
-		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce).enabled;
+		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning")).enabled;
 		enabled = resolveEnabled({ config, flag: readFlag(), live: liveOverride });
 		return enabled;
 	};

package/extensions/provider-stall-watchdog.ts

@@ -91,8 +91,8 @@ export function resolveRetryMaxRetries(cwd: string): number {
 	return maxRetries;
 }
 
-export function resolveWatchdogConfig(cwd: string): ConfigValidation {
-	const candidate = resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce);
+export function resolveWatchdogConfig(cwd: string, warn?: (msg: string) => void): ConfigValidation {
+	const candidate = resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce, warn);
 	if (candidate.blockIsObject === true && candidate.maxStallRetries === undefined) {
 		candidate.maxStallRetries = resolveRetryMaxRetries(cwd);
 	}
@@ -278,7 +278,7 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 			ui = ctx.ui;
 			hasUI = ctx.hasUI;
 			if (!config) {
-				const resolved = resolveWatchdogConfig(ctx.cwd);
+				const resolved = resolveWatchdogConfig(ctx.cwd, (m) => announce(m, "warning"));
 				if (!resolved.ok) {
 					disabled = true;
 					announce(`providerStallWatchdog disabled: ${resolved.error}`, "warning");

package/extensions/session-name.ts

@@ -96,7 +96,7 @@ export function coerce(raw: unknown): Partial<Config> | undefined {
 }
 
 function loadConfig(ctx: ExtensionContext): Config {
-	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce);
+	return resolveConfig(ctx.cwd, "sessionAutoName", DEFAULT_CONFIG, coerce, (m) => ctx.ui.notify(m, "warning"));
 }
 
 type ContentBlock = { type?: string; text?: string };