pi-quiver 3.1.2 → 3.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.
 
+## v3.2.0 - 2026-07-12
+
+- Add `fast-mode` extension: opt-in Anthropic fast mode for Claude Opus 4.8 (`speed: "fast"` payload + `fast-mode-2026-02-01` beta header), controlled via `fastMode` settings key, `--fast` flag, and `/fast [on|off|status]`. OFF by default. Preserves OAuth identity betas. Requires pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5 (the `before_provider_headers` hook).
+
 ## v3.1.2 - 2026-07-07
 
 - **`fetch` routes GitHub Actions run URLs through `gh`.** `github.com/{owner}/{repo}/actions/runs/{id}` URLs are served by `gh run view {id} --repo {owner}/{repo}` and returned through the existing size gate with a `Source: gh run view ...` header, alongside the existing issue/PR/repo routing. Only the bare run URL routes; deeper paths (`.../runs/{id}/jobs/{jobId}`, `.../actions/workflows/{file}`) fall back to HTTP. Falls back silently when `gh` is absent/unauthenticated/errors; `raw=true` forces the rendered page.

package/README.md

@@ -66,6 +66,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
 | `session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, with Ghostty tab rename. OFF by default. |
 | `sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
+| `fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
 
 Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md), [doc/doc-to-md.md](doc/doc-to-md.md).
 
@@ -130,18 +131,19 @@ The npm package's bundled JS deps install automatically on `pi install`. A few *
 
 None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
 
-### session-name and sword-header config
+### Opt-in extension config
 
 Both are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
 
 ```jsonc
 {
   "sessionAutoName": { "enabled": false, "ghosttyTab": true }, // or boolean shorthand
-  "swordHeader": false                                         // or { "enabled": true }
+  "swordHeader": false,                                        // or { "enabled": true }
+  "fastMode": false                                            // or { "enabled": true }
 }
 ```
 
-`sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. 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.
+`sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `fastMode` only affects `claude-opus-4-8` 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.
 
 ## Development
 

package/fast-mode.ts

@@ -0,0 +1,182 @@
+/**
+ * Fast mode for Claude Opus 4.8.
+ *
+ * When enabled, injects Anthropic's fast-mode signals into every qualifying
+ * Opus 4.8 request on the anthropic-messages API, regardless of thinking level:
+ *   - payload: { ...payload, speed: "fast" }        (before_provider_request)
+ *   - header:  anthropic-beta: ...,fast-mode-2026-02-01  (before_provider_headers)
+ *
+ * OFF BY DEFAULT. Three control surfaces, lowest precedence first:
+ *   1. settings.json  "fastMode": true | { "enabled": true }  (default false)
+ *   2. --fast launch flag                                      (force-on only)
+ *   3. /fast [on|off|status] live toggle                       (wins for session)
+ *
+ * Header coupling to pi-ai internals: pi assembles `anthropic-beta` AFTER this
+ * hook and merges the hook's headers LAST, so setting the header here REPLACES
+ * pi's list. For opus-4-8 pi's conditional betas (fine-grained tool streaming,
+ * interleaved thinking) are never applied (eager tool streaming defaults on +
+ * forceAdaptiveThinking), so the only betas to preserve are the OAuth identity
+ * betas. We detect OAuth via the same token marker pi uses and rebuild the
+ * exact list. If pi later adds betas for opus-4-8, revisit buildBetaHeader.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveConfig } from "./extension-config.ts";
+
+export const FAST_MODE_BETA = "fast-mode-2026-02-01";
+export const FAST_SPEED = "fast";
+// Loose prefix: matches dated snapshots (claude-opus-4-8-*). Opus 4.7 is out of
+// scope (D1); a future 4.9 needs a one-line addition here.
+export const FAST_MODE_MODEL_PREFIXES = ["claude-opus-4-8"];
+export const OAUTH_IDENTITY_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
+const STATUS_KEY = "fast-mode";
+const BETA_HEADER = "anthropic-beta";
+
+type Config = { enabled: boolean };
+const DEFAULT_CONFIG: Config = { enabled: false };
+
+export function coerce(raw: unknown): Partial<Config> | undefined {
+	if (raw === undefined) return undefined;
+	if (typeof raw === "boolean") return { enabled: raw };
+	if (raw && typeof raw === "object") {
+		const o = raw as Record<string, unknown>;
+		const out: Partial<Config> = {};
+		if (typeof o.enabled === "boolean") out.enabled = o.enabled;
+		return out;
+	}
+	return undefined;
+}
+
+type ModelLike = { id?: string; api?: string; provider?: string } | undefined;
+
+export function shouldInject(enabled: boolean, model: ModelLike): boolean {
+	if (!enabled || !model) return false;
+	if (model.provider !== "anthropic") return false;
+	if (model.api !== "anthropic-messages") return false;
+	const id = model.id;
+	if (typeof id !== "string") return false;
+	return FAST_MODE_MODEL_PREFIXES.some((p) => id.startsWith(p));
+}
+
+export function injectSpeed(payload: unknown): unknown {
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+		return payload;
+	}
+	return { ...(payload as Record<string, unknown>), speed: FAST_SPEED };
+}
+
+export function buildBetaHeader(existing: string | null | undefined, isOAuth: boolean): string {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	const add = (b: string): void => {
+		const t = b.trim();
+		if (t && !seen.has(t)) {
+			seen.add(t);
+			out.push(t);
+		}
+	};
+	if (isOAuth) OAUTH_IDENTITY_BETAS.forEach(add);
+	if (typeof existing === "string") existing.split(",").forEach(add);
+	add(FAST_MODE_BETA);
+	return out.join(",");
+}
+
+type State = { config: boolean; flag: boolean; live: boolean | null };
+
+export function resolveEnabled(s: State): boolean {
+	if (s.live !== null) return s.live;
+	return s.flag || s.config;
+}
+
+export default function (pi: ExtensionAPI) {
+	let liveOverride: boolean | null = null;
+	let enabled = false;
+
+	const readFlag = (): boolean => pi.getFlag("fast") === true;
+
+	const resolveState = (ctx: ExtensionContext): boolean => {
+		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce).enabled;
+		enabled = resolveEnabled({ config, flag: readFlag(), live: liveOverride });
+		return enabled;
+	};
+
+	const refreshStatus = (ctx: ExtensionContext): void => {
+		if (!enabled) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		ctx.ui.setStatus(STATUS_KEY, shouldInject(enabled, ctx.model) ? "\u26a1 fast" : "\u26a1 n/a");
+	};
+
+	const detectOAuth = async (ctx: ExtensionContext): Promise<boolean | null> => {
+		if (!ctx.model) return null;
+		try {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+			if (!auth.ok) return null;
+			return typeof auth.apiKey === "string" && auth.apiKey.includes("sk-ant-oat");
+		} catch {
+			return null;
+		}
+	};
+
+	pi.registerFlag("fast", {
+		type: "boolean",
+		description: "Enable Anthropic fast mode for Opus 4.8 requests this launch",
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		resolveState(ctx);
+		refreshStatus(ctx);
+	});
+
+	pi.on("model_select", async (_event, ctx) => {
+		refreshStatus(ctx);
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		if (!shouldInject(enabled, ctx.model)) return;
+		return injectSpeed(event.payload);
+	});
+
+	pi.on("before_provider_headers", async (event, ctx) => {
+		if (!shouldInject(enabled, ctx.model)) return;
+		if (!event.headers) return;
+		const isOAuth = await detectOAuth(ctx);
+		if (isOAuth === null) return;
+		event.headers[BETA_HEADER] = buildBetaHeader(event.headers[BETA_HEADER], isOAuth);
+	});
+
+	pi.registerCommand("fast", {
+		description: "Manage Opus 4.8 fast mode: /fast [on|off|status]",
+		getArgumentCompletions: (prefix) => {
+			const p = prefix.trim().toLowerCase();
+			if (p.includes(" ")) return null;
+			const matches = ["on", "off", "status"].filter((v) => v.startsWith(p));
+			return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+			if (arg === "status") {
+				const eff = liveOverride !== null ? "live toggle" : readFlag() ? "--fast flag" : "settings.json";
+				const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(no model selected)";
+				const applies = shouldInject(enabled, ctx.model) ? "applies to current model" : "does not apply to current model";
+				ctx.ui.notify(
+					`Fast mode is ${enabled ? "on" : "off"} (source: ${eff}). Model: ${model} - ${applies}.`,
+					"info",
+				);
+				return;
+			}
+			if (arg === "on" || arg === "off") {
+				liveOverride = arg === "on";
+			} else if (arg === "") {
+				liveOverride = !enabled;
+			} else {
+				ctx.ui.notify("Usage: /fast [on|off|status]", "warning");
+				return;
+			}
+			resolveState(ctx);
+			refreshStatus(ctx);
+			ctx.ui.notify(`Fast mode ${enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, and a themed ASCII startup header.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "doc_to_md.ts",
     "session-name.ts",
     "sword-header.ts",
+    "fast-mode.ts",
     "extension-config.ts",
     "scripts/pdf_to_md.py",
     "types/**/*.d.ts",
@@ -41,7 +42,7 @@
   "scripts": {
     "check:agents-core": "node scripts/check-agents-core.mjs",
     "test": "node --test \"*.test.ts\"",
-    "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
+    "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts fast-mode.ts fast-mode.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
     "test:all": "npm run check:agents-core && npm run test && npm run typecheck"
   },
   "pi": {
@@ -49,7 +50,8 @@
       "./fetch.ts",
       "./doc_to_md.ts",
       "./session-name.ts",
-      "./sword-header.ts"
+      "./sword-header.ts",
+      "./fast-mode.ts"
     ],
     "image": "https://raw.githubusercontent.com/jjuraszek/pi-quiver/main/pi-quiver.png"
   },
@@ -86,7 +88,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.80.3",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.5",
     "@earendil-works/pi-tui": "^0.80.3",
     "@sinclair/typebox": "^0.34.49",
     "@types/jsdom": "^28.0.3",