pi-meta-oauth 0.4.4 → 0.5.0

package/README.md

@@ -8,7 +8,8 @@
 
 Meta Model API OAuth and Muse-style voice input for [pi](https://pi.dev).
 
-- Use Muse Spark models through Pi's `openai-responses` provider
+- Use Muse Spark models through Pi's `openai-responses` provider (not `/chat/completions` — Muse prompt cache is ~0% there)
+- Send `prompt_cache_retention: "24h"` on Meta Responses requests unless the payload already set a retention
 - Device authorization against `https://auth.meta.com`
 - Model API-key minting through `POST https://api.meta.ai/muse-code/key`
 - Dynamic Muse model catalog from `GET https://api.meta.ai/v1/models`
@@ -87,11 +88,13 @@ Fallback models use a 1,048,576-token context window, up to 256K output tokens,
 
 | id | pricing (input/output/cached) $/M |
 | --- | --- |
+| `muse-spark-1.3` | 1.25 / 4.25 / 0.15 |
+| `muse-spark-1.3-contributor` | 0.10 / 0.20 / 0.002 |
 | `muse-spark-1.2` | 1.25 / 4.25 / 0.15 |
 | `muse-spark-1.2-contributor` | 0.10 / 0.20 / 0.002 |
 | `muse-spark-1.1` | 1.25 / 4.25 / 0.15 |
 
-> **Contributor-model privacy:** the discounted contributor model allows Meta to use prompts and completions for product improvement, including training future Meta models. Use the standard `muse-spark-1.2` model if you do not want the contributor terms. See [Meta's model documentation](https://dev.meta.ai/docs/models).
+> **Contributor-model privacy:** discounted contributor models allow Meta to use prompts and completions for product improvement, including training future Meta models. Use a standard model such as `muse-spark-1.3` if you do not want the contributor terms. See [Meta's model documentation](https://dev.meta.ai/docs/models).
 
 To scope Pi's model picker to Meta models:
 
@@ -122,11 +125,19 @@ catalog.
 
 ```bash
 pi --list-models meta
-pi -p --provider meta --model muse-spark-1.2 "Reply exactly: META_OK"
+pi -p --provider meta --model muse-spark-1.3 "Reply exactly: META_OK"
 bun run typecheck
 bun test
 ```
 
+`bun test` is hermetic unless a Meta credential is already available. The live cache-hit probe makes real billable API calls when a credential resolves: two identical `/v1/responses` calls (asserting `cached_tokens` on the second), plus one 2s retry if that second call misses cache. The credential is resolved, in order, from `PI_META_LIVE_API_KEY`, `META_API_KEY`, `MODEL_API_KEY`, or the minted key from `~/.pi/agent/auth.json` after `/login meta` (skipped if expired). OAuth is enough — you do not need a separate key. Skipped when no valid credential exists (CI):
+
+```bash
+bun test tests/meta-cache.test.ts
+# or, if you are not logged in:
+PI_META_LIVE_API_KEY='LLM|...' bun test tests/meta-cache.test.ts
+```
+
 ## Publish to npm and pi.dev
 
 The `pi-package` keyword makes the package discoverable at <https://pi.dev/packages>. Publishing is handled by `.github/workflows/publish.yml` when a `v*` tag is pushed. Each release publishes the canonical `pi-meta-oauth` package to npm and a scoped `@blockedpath/pi-meta-oauth` mirror to GitHub Packages.

package/extensions/media/responses.ts

@@ -1,5 +1,9 @@
 import type { Usage } from "@earendil-works/pi-ai";
-import { META_API_BASE_URL, metaFallbackCost } from "../meta.ts";
+import {
+	applyMetaResponsesCacheHints,
+	META_API_BASE_URL,
+	metaFallbackCost,
+} from "../meta.ts";
 
 function record(value: unknown): Record<string, unknown> | undefined {
 	return value !== null && typeof value === "object"
@@ -20,7 +24,11 @@ function tokenCount(...values: unknown[]): number | undefined {
 	return undefined;
 }
 
-function responsesErrorDetail(json: unknown, text: string, statusText: string): string {
+function responsesErrorDetail(
+	json: unknown,
+	text: string,
+	statusText: string,
+): string {
 	const body = record(json);
 	if (body?.error !== undefined) {
 		return JSON.stringify(body.error).slice(0, 1000);
@@ -77,10 +85,8 @@ export function extractMetaResponseUsage(
 	const outputTokens = output ?? 0;
 	const reasoning = Math.min(
 		outputTokens,
-		tokenCount(
-			outputDetails?.reasoning_tokens,
-			outputDetails?.reasoningTokens,
-		) ?? 0,
+		tokenCount(outputDetails?.reasoning_tokens, outputDetails?.reasoningTokens) ??
+			0,
 	);
 	const totalTokens =
 		tokenCount(usage.total_tokens, usage.totalTokens) ??
@@ -127,8 +133,7 @@ export function extractResponsesText(json: unknown): string {
 	if (Array.isArray(output)) {
 		const texts: string[] = [];
 		for (const item of output as Record<string, unknown>[]) {
-			if (!item || typeof item !== "object" || item.type !== "message")
-				continue;
+			if (!item || typeof item !== "object" || item.type !== "message") continue;
 			if (typeof item.content === "string" && item.content.trim())
 				texts.push(item.content);
 			if (Array.isArray(item.content)) {
@@ -160,6 +165,7 @@ export async function callMetaResponses(
 	signal?: AbortSignal,
 ): Promise<{ text: string; raw: unknown }> {
 	payload.store = false;
+	applyMetaResponsesCacheHints(payload);
 	const res = await fetch(`${META_API_BASE_URL}/responses`, {
 		method: "POST",
 		headers: {

package/extensions/media.ts

@@ -48,7 +48,10 @@ import {
 } from "./media/responses.ts";
 
 export { mediaInputFromSource } from "./media/mime.ts";
-export { maybeUploadLargeInlineBlocks, rewriteResponsesPayload } from "./media/payload.ts";
+export {
+	maybeUploadLargeInlineBlocks,
+	rewriteResponsesPayload,
+} from "./media/payload.ts";
 export {
 	extractMetaResponseUsage,
 	extractResponsesText,
@@ -205,13 +208,12 @@ export default function metaMedia(pi: ExtensionAPI): void {
 			}
 			if (apiKey) {
 				try {
-					const { payload: uploadedPayload } =
-						await maybeUploadLargeInlineBlocks(
-							payloadToCheck,
-							apiKey,
-							STORE_SAFE_INLINE_BYTES,
-							ctx.signal,
-						);
+					const { payload: uploadedPayload } = await maybeUploadLargeInlineBlocks(
+						payloadToCheck,
+						apiKey,
+						STORE_SAFE_INLINE_BYTES,
+						ctx.signal,
+					);
 					return uploadedPayload as unknown;
 				} catch {
 					const fallback = payloadToCheck as Record<string, unknown>;
@@ -296,7 +298,8 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		label: "Meta Video Describe",
 		description:
 			"Analyze an MP4 video with Muse Spark, including visuals and embedded speech. Accepts a local path, public HTTPS/data URL, or Meta file_id. Results are capped by max_chars; when truncated, the full text is saved to a temp file for continuation with read offset/limit.",
-		promptSnippet: "Inspect video and embedded audio when the active model cannot",
+		promptSnippet:
+			"Inspect video and embedded audio when the active model cannot",
 		promptGuidelines: [
 			"Use meta_describe_video when the task depends on an MP4 video the active model cannot inspect directly.",
 			"Give meta_describe_video a task-specific prompt that asks for the exact visual, transcript, timestamp, or defect evidence needed next.",
@@ -304,31 +307,55 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		],
 		parameters: Type.Object(
 			{
-				path: Type.Optional(Type.String({ description: "Local .mp4/.m4v path, relative to cwd or absolute" })),
-				url: Type.Optional(Type.String({ description: "Public HTTPS or data:video/mp4 URL" })),
-				file_id: Type.Optional(Type.String({ description: "Existing Meta Files API id" })),
-				prompt: Type.String({ description: "What evidence to extract from the video" }),
-				model: Type.Optional(Type.String({ description: "Muse model id, default muse-spark-1.2" })),
-				max_output_tokens: Type.Optional(Type.Integer({
-					minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
-					maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
-					description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
-				})),
-				max_chars: Type.Optional(Type.Integer({
-					minimum: 1_000,
-					maximum: MAX_MEDIA_MAX_CHARS,
-					description: `Maximum result characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
-				})),
+				path: Type.Optional(
+					Type.String({
+						description: "Local .mp4/.m4v path, relative to cwd or absolute",
+					}),
+				),
+				url: Type.Optional(
+					Type.String({ description: "Public HTTPS or data:video/mp4 URL" }),
+				),
+				file_id: Type.Optional(
+					Type.String({ description: "Existing Meta Files API id" }),
+				),
+				prompt: Type.String({
+					description: "What evidence to extract from the video",
+				}),
+				model: Type.Optional(
+					Type.String({ description: "Muse model id, default muse-spark-1.2" }),
+				),
+				max_output_tokens: Type.Optional(
+					Type.Integer({
+						minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
+						maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
+						description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
+					}),
+				),
+				max_chars: Type.Optional(
+					Type.Integer({
+						minimum: 1_000,
+						maximum: MAX_MEDIA_MAX_CHARS,
+						description: `Maximum result characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
+					}),
+				),
 			},
 			{ additionalProperties: false },
 		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, prompt, model, max_output_tokens, max_chars } = params as {
-				path?: string; url?: string; file_id?: string; prompt: string; model?: string;
-				max_output_tokens?: number; max_chars?: number;
-			};
+			const { path, url, file_id, prompt, model, max_output_tokens, max_chars } =
+				params as {
+					path?: string;
+					url?: string;
+					file_id?: string;
+					prompt: string;
+					model?: string;
+					max_output_tokens?: number;
+					max_chars?: number;
+				};
 			if ([path, url, file_id].filter(Boolean).length !== 1) {
-				throw new Error("meta_describe_video requires exactly one of path, url, or file_id");
+				throw new Error(
+					"meta_describe_video requires exactly one of path, url, or file_id",
+				);
 			}
 			try {
 				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
@@ -341,26 +368,51 @@ export default function metaMedia(pi: ExtensionAPI): void {
 					const absolute = resolve(ctx.cwd, path as string);
 					if (!existsSync(absolute)) throw new Error(`File not found: ${absolute}`);
 					const stat = statSync(absolute);
-					if (stat.size > FILES_API_LIMIT_BYTES) throw new Error(`File too large (1 GiB limit): ${path}`);
+					if (stat.size > FILES_API_LIMIT_BYTES)
+						throw new Error(`File too large (1 GiB limit): ${path}`);
 					rejectWrongMime("video", path as string, mimeForPath(absolute));
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const upload = await uploadMetaFile(apiKey, absolute, automaticExpiry(), signal);
+						const upload = await uploadMetaFile(
+							apiKey,
+							absolute,
+							automaticExpiry(),
+							signal,
+						);
 						videoBlock = { type: "input_file", file_id: upload.id };
 					} else {
-						videoBlock = mediaInputFromSource(dataUrlForFile(absolute).dataUrl, basename(absolute), "video/mp4");
+						videoBlock = mediaInputFromSource(
+							dataUrlForFile(absolute).dataUrl,
+							basename(absolute),
+							"video/mp4",
+						);
 					}
 				}
 				const selectedModel = model ?? "muse-spark-1.2";
-				const { text, raw } = await callMetaResponses(apiKey, {
-					model: selectedModel,
-					store: false,
-					input: [{ type: "message", role: "user", content: [
-						{ type: "input_text", text: prompt },
-						videoBlock as Record<string, unknown>,
-					] }],
-					max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
-				}, signal);
-				const output = await prepareMediaOutput({ text, response: raw, identity: toolCallId, maxChars: max_chars });
+				const { text, raw } = await callMetaResponses(
+					apiKey,
+					{
+						model: selectedModel,
+						store: false,
+						input: [
+							{
+								type: "message",
+								role: "user",
+								content: [
+									{ type: "input_text", text: prompt },
+									videoBlock as Record<string, unknown>,
+								],
+							},
+						],
+						max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
+					},
+					signal,
+				);
+				const output = await prepareMediaOutput({
+					text,
+					response: raw,
+					identity: toolCallId,
+					maxChars: max_chars,
+				});
 				const usage = extractMetaResponseUsage(raw, selectedModel);
 				return {
 					content: [{ type: "text", text: output.text }],
@@ -386,30 +438,52 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		parameters: Type.Object(
 			{
 				path: Type.Optional(Type.String({ description: "Local .wav/.mp3 path" })),
-				url: Type.Optional(Type.String({ description: "Public HTTPS or data audio URL" })),
-				file_id: Type.Optional(Type.String({ description: "Existing Meta Files API id" })),
-				prompt: Type.Optional(Type.String({ description: "Transcription or audio-analysis instruction" })),
-				model: Type.Optional(Type.String({ description: "Muse model id, default muse-spark-1.2" })),
-				max_output_tokens: Type.Optional(Type.Integer({
-					minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
-					maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
-					description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
-				})),
-				max_chars: Type.Optional(Type.Integer({
-					minimum: 1_000,
-					maximum: MAX_MEDIA_MAX_CHARS,
-					description: `Maximum transcript characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
-				})),
+				url: Type.Optional(
+					Type.String({ description: "Public HTTPS or data audio URL" }),
+				),
+				file_id: Type.Optional(
+					Type.String({ description: "Existing Meta Files API id" }),
+				),
+				prompt: Type.Optional(
+					Type.String({
+						description: "Transcription or audio-analysis instruction",
+					}),
+				),
+				model: Type.Optional(
+					Type.String({ description: "Muse model id, default muse-spark-1.2" }),
+				),
+				max_output_tokens: Type.Optional(
+					Type.Integer({
+						minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
+						maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
+						description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
+					}),
+				),
+				max_chars: Type.Optional(
+					Type.Integer({
+						minimum: 1_000,
+						maximum: MAX_MEDIA_MAX_CHARS,
+						description: `Maximum transcript characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
+					}),
+				),
 			},
 			{ additionalProperties: false },
 		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, prompt, model, max_output_tokens, max_chars } = params as {
-				path?: string; url?: string; file_id?: string; prompt?: string; model?: string;
-				max_output_tokens?: number; max_chars?: number;
-			};
+			const { path, url, file_id, prompt, model, max_output_tokens, max_chars } =
+				params as {
+					path?: string;
+					url?: string;
+					file_id?: string;
+					prompt?: string;
+					model?: string;
+					max_output_tokens?: number;
+					max_chars?: number;
+				};
 			if ([path, url, file_id].filter(Boolean).length !== 1) {
-				throw new Error("meta_transcribe_audio requires exactly one of path, url, or file_id");
+				throw new Error(
+					"meta_transcribe_audio requires exactly one of path, url, or file_id",
+				);
 			}
 			try {
 				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
@@ -422,27 +496,55 @@ export default function metaMedia(pi: ExtensionAPI): void {
 					const absolute = resolve(ctx.cwd, path as string);
 					if (!existsSync(absolute)) throw new Error(`File not found: ${absolute}`);
 					const stat = statSync(absolute);
-					if (stat.size > FILES_API_LIMIT_BYTES) throw new Error("Audio too large (1 GiB limit)");
+					if (stat.size > FILES_API_LIMIT_BYTES)
+						throw new Error("Audio too large (1 GiB limit)");
 					const mime = mimeForPath(absolute);
 					rejectWrongMime("audio", path as string, mime);
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const upload = await uploadMetaFile(apiKey, absolute, automaticExpiry(), signal);
+						const upload = await uploadMetaFile(
+							apiKey,
+							absolute,
+							automaticExpiry(),
+							signal,
+						);
 						audioBlock = { type: "input_file", file_id: upload.id };
 					} else {
-						audioBlock = mediaInputFromSource(dataUrlForFile(absolute).dataUrl, basename(absolute), mime);
+						audioBlock = mediaInputFromSource(
+							dataUrlForFile(absolute).dataUrl,
+							basename(absolute),
+							mime,
+						);
 					}
 				}
 				const selectedModel = model ?? "muse-spark-1.2";
-				const { text, raw } = await callMetaResponses(apiKey, {
-					model: selectedModel,
-					store: false,
-					input: [{ type: "message", role: "user", content: [
-						{ type: "input_text", text: prompt ?? "Transcribe this audio. Return only the transcript." },
-						audioBlock as Record<string, unknown>,
-					] }],
-					max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
-				}, signal);
-				const output = await prepareMediaOutput({ text, response: raw, identity: toolCallId, maxChars: max_chars });
+				const { text, raw } = await callMetaResponses(
+					apiKey,
+					{
+						model: selectedModel,
+						store: false,
+						input: [
+							{
+								type: "message",
+								role: "user",
+								content: [
+									{
+										type: "input_text",
+										text: prompt ?? "Transcribe this audio. Return only the transcript.",
+									},
+									audioBlock as Record<string, unknown>,
+								],
+							},
+						],
+						max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
+					},
+					signal,
+				);
+				const output = await prepareMediaOutput({
+					text,
+					response: raw,
+					identity: toolCallId,
+					maxChars: max_chars,
+				});
 				const usage = extractMetaResponseUsage(raw, selectedModel);
 				return {
 					content: [{ type: "text", text: output.text }],
@@ -463,30 +565,42 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		parameters: Type.Object(
 			{
 				path: Type.String({ description: "Local file path to upload" }),
-				expires_after_seconds: Type.Optional(Type.Integer({
-					minimum: MIN_UPLOAD_EXPIRY_SECONDS,
-					maximum: MAX_UPLOAD_EXPIRY_SECONDS,
-					description: `Expiry in seconds, default ${EXPLICIT_UPLOAD_EXPIRY_SECONDS} (7 days)`,
-				})),
-				retain: Type.Optional(Type.Boolean({ description: "Keep indefinitely instead of applying an expiry" })),
+				expires_after_seconds: Type.Optional(
+					Type.Integer({
+						minimum: MIN_UPLOAD_EXPIRY_SECONDS,
+						maximum: MAX_UPLOAD_EXPIRY_SECONDS,
+						description: `Expiry in seconds, default ${EXPLICIT_UPLOAD_EXPIRY_SECONDS} (7 days)`,
+					}),
+				),
+				retain: Type.Optional(
+					Type.Boolean({
+						description: "Keep indefinitely instead of applying an expiry",
+					}),
+				),
 			},
 			{ additionalProperties: false },
 		),
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const { path, expires_after_seconds, retain } = params as {
-				path: string; expires_after_seconds?: number; retain?: boolean;
+				path: string;
+				expires_after_seconds?: number;
+				retain?: boolean;
 			};
 			if (retain && expires_after_seconds !== undefined) {
-				throw new Error("meta_upload_file accepts either retain=true or expires_after_seconds, not both");
+				throw new Error(
+					"meta_upload_file accepts either retain=true or expires_after_seconds, not both",
+				);
 			}
 			try {
 				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
 				const absolute = resolve(ctx.cwd, path);
 				if (!existsSync(absolute)) throw new Error(`File not found: ${absolute}`);
-				const expiresAfter = retain ? undefined : {
-					anchor: "created_at" as const,
-					seconds: expires_after_seconds ?? EXPLICIT_UPLOAD_EXPIRY_SECONDS,
-				};
+				const expiresAfter = retain
+					? undefined
+					: {
+							anchor: "created_at" as const,
+							seconds: expires_after_seconds ?? EXPLICIT_UPLOAD_EXPIRY_SECONDS,
+						};
 				const result = await uploadMetaFile(apiKey, absolute, expiresAfter, signal);
 				const retention = retain
 					? "retained without expiry"
@@ -494,7 +608,12 @@ export default function metaMedia(pi: ExtensionAPI): void {
 						? `expires_at ${result.expires_at}`
 						: `expires after ${expiresAfter?.seconds} seconds`;
 				return {
-					content: [{ type: "text", text: `Uploaded ${basename(absolute)} to ${result.id} (${result.bytes} bytes, ${retention}).` }],
+					content: [
+						{
+							type: "text",
+							text: `Uploaded ${basename(absolute)} to ${result.id} (${result.bytes} bytes, ${retention}).`,
+						},
+					],
 					details: result,
 				};
 			} catch (error) {
@@ -508,7 +627,8 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		label: "Meta File Analyze",
 		description:
 			"Analyze one or more images, PDFs, videos, or audio files with Muse Spark. Use path/url/file_id for one source, or ordered sources for comparisons. Images and PDF pages share Meta's 50-image budget; PDFs include text from the first 100 pages and images from the first 50 pages. Truncated text is saved for continuation with read offset/limit.",
-		promptSnippet: "Inspect images, PDFs, or mixed media when the active model cannot",
+		promptSnippet:
+			"Inspect images, PDFs, or mixed media when the active model cannot",
 		promptGuidelines: [
 			"Use meta_analyze_file when the task depends on an image, PDF, or generic media file the active model cannot inspect directly.",
 			"Give meta_analyze_file a task-specific prompt that asks for the exact visible text, layout, comparison, defect, or action evidence needed next.",
@@ -517,61 +637,134 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		parameters: Type.Object(
 			{
 				path: Type.Optional(Type.String({ description: "Single local file path" })),
-				url: Type.Optional(Type.String({ description: "Single public HTTPS or data URL" })),
-				file_id: Type.Optional(Type.String({ description: "Single existing Meta file_id" })),
-				sources: Type.Optional(Type.Array(Type.Object({
-					source: Type.String({ description: "Local path, HTTPS/data URL, or Meta file_id" }),
-					label: Type.Optional(Type.String({ description: "Human-readable label such as Before or After" })),
-				}, { additionalProperties: false }), {
-					minItems: 1,
-					maxItems: MAX_ANALYSIS_SOURCES,
-					description: "Ordered sources for comparison or combined analysis",
-				})),
+				url: Type.Optional(
+					Type.String({ description: "Single public HTTPS or data URL" }),
+				),
+				file_id: Type.Optional(
+					Type.String({ description: "Single existing Meta file_id" }),
+				),
+				sources: Type.Optional(
+					Type.Array(
+						Type.Object(
+							{
+								source: Type.String({
+									description: "Local path, HTTPS/data URL, or Meta file_id",
+								}),
+								label: Type.Optional(
+									Type.String({
+										description: "Human-readable label such as Before or After",
+									}),
+								),
+							},
+							{ additionalProperties: false },
+						),
+						{
+							minItems: 1,
+							maxItems: MAX_ANALYSIS_SOURCES,
+							description: "Ordered sources for comparison or combined analysis",
+						},
+					),
+				),
 				prompt: Type.String({ description: "What evidence to extract or compare" }),
-				model: Type.Optional(Type.String({ description: "Muse model id, default muse-spark-1.2" })),
-				max_output_tokens: Type.Optional(Type.Integer({
-					minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
-					maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
-					description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
-				})),
-				max_chars: Type.Optional(Type.Integer({
-					minimum: 1_000,
-					maximum: MAX_MEDIA_MAX_CHARS,
-					description: `Maximum result characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
-				})),
+				model: Type.Optional(
+					Type.String({ description: "Muse model id, default muse-spark-1.2" }),
+				),
+				max_output_tokens: Type.Optional(
+					Type.Integer({
+						minimum: MIN_MEDIA_MAX_OUTPUT_TOKENS,
+						maximum: MAX_MEDIA_MAX_OUTPUT_TOKENS,
+						description: `Muse generation budget, default ${DEFAULT_MEDIA_MAX_OUTPUT_TOKENS}`,
+					}),
+				),
+				max_chars: Type.Optional(
+					Type.Integer({
+						minimum: 1_000,
+						maximum: MAX_MEDIA_MAX_CHARS,
+						description: `Maximum result characters returned inline, default ${DEFAULT_MEDIA_MAX_CHARS}`,
+					}),
+				),
 			},
 			{ additionalProperties: false },
 		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, sources, prompt, model, max_output_tokens, max_chars } = params as {
-				path?: string; url?: string; file_id?: string; sources?: AnalysisSource[];
-				prompt: string; model?: string; max_output_tokens?: number; max_chars?: number;
+			const {
+				path,
+				url,
+				file_id,
+				sources,
+				prompt,
+				model,
+				max_output_tokens,
+				max_chars,
+			} = params as {
+				path?: string;
+				url?: string;
+				file_id?: string;
+				sources?: AnalysisSource[];
+				prompt: string;
+				model?: string;
+				max_output_tokens?: number;
+				max_chars?: number;
 			};
-			const legacySources = [path, url, file_id].filter((value): value is string => Boolean(value));
-			if (legacySources.length > 1 || (legacySources.length === 1 && sources) || (legacySources.length === 0 && !sources)) {
-				throw new Error("meta_analyze_file requires exactly one path/url/file_id or a sources array");
+			const legacySources = [path, url, file_id].filter((value): value is string =>
+				Boolean(value),
+			);
+			if (
+				legacySources.length > 1 ||
+				(legacySources.length === 1 && sources) ||
+				(legacySources.length === 0 && !sources)
+			) {
+				throw new Error(
+					"meta_analyze_file requires exactly one path/url/file_id or a sources array",
+				);
 			}
 			if (sources && sources.length > MAX_ANALYSIS_SOURCES) {
-				throw new Error(`meta_analyze_file supports at most ${MAX_ANALYSIS_SOURCES} sources`);
+				throw new Error(
+					`meta_analyze_file supports at most ${MAX_ANALYSIS_SOURCES} sources`,
+				);
 			}
 			try {
 				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
-				const requestedSources: AnalysisSource[] = sources ?? [{ source: legacySources[0] as string }];
-				const content: ResponsesContentBlock[] = [{ type: "input_text", text: prompt }];
+				const requestedSources: AnalysisSource[] = sources ?? [
+					{ source: legacySources[0] as string },
+				];
+				const content: ResponsesContentBlock[] = [
+					{ type: "input_text", text: prompt },
+				];
 				for (const [index, item] of requestedSources.entries()) {
 					if (requestedSources.length > 1 || item.label) {
-						content.push({ type: "input_text", text: `${sourceLabel(item, index)}:` });
+						content.push({
+							type: "input_text",
+							text: `${sourceLabel(item, index)}:`,
+						});
 					}
-					content.push(await resolveGenericMediaSource(apiKey, ctx.cwd, item.source, signal));
+					content.push(
+						await resolveGenericMediaSource(apiKey, ctx.cwd, item.source, signal),
+					);
 				}
 				const selectedModel = model ?? "muse-spark-1.2";
-				const { text, raw } = await callMetaResponses(apiKey, {
-					model: selectedModel,
-					store: false,
-					input: [{ type: "message", role: "user", content: content as Record<string, unknown>[] }],
-					max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
-				}, signal);
-				const output = await prepareMediaOutput({ text, response: raw, identity: toolCallId, maxChars: max_chars });
+				const { text, raw } = await callMetaResponses(
+					apiKey,
+					{
+						model: selectedModel,
+						store: false,
+						input: [
+							{
+								type: "message",
+								role: "user",
+								content: content as Record<string, unknown>[],
+							},
+						],
+						max_output_tokens: mediaMaxOutputTokens(max_output_tokens),
+					},
+					signal,
+				);
+				const output = await prepareMediaOutput({
+					text,
+					response: raw,
+					identity: toolCallId,
+					maxChars: max_chars,
+				});
 				const usage = extractMetaResponseUsage(raw, selectedModel);
 				return {
 					content: [{ type: "text", text: output.text }],
@@ -737,8 +930,7 @@ export default function metaMedia(pi: ExtensionAPI): void {
 				const apiKey = await safeGetMetaApiKey(ctx as unknown as ExtensionContext);
 				let block: ResponsesContentBlock;
 				if (isFileId(source)) block = { type: "input_file", file_id: source };
-				else if (isRemoteMediaSource(source))
-					block = mediaInputFromSource(source);
+				else if (isRemoteMediaSource(source)) block = mediaInputFromSource(source);
 				else {
 					const abs = resolve(cwd, source);
 					if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);

package/extensions/meta.ts

@@ -82,6 +82,56 @@ interface MetaCatalogModel {
 // See media.ts for the before_provider_request rewrite that makes @video/@audio work today
 // despite UserMessage.content being string | (TextContent | ImageContent)[] .
 const FALLBACK_MODELS: MetaProviderModel[] = [
+	{
+		id: "muse-spark-1.3",
+		name: "Muse Spark 1.3",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		// SAFETY: Meta supports video/audio inputs, while pi-ai 0.83/0.84 types only expose text/image.
+		input: [
+			"text",
+			"image",
+			"video",
+			"audio",
+		] as unknown as MetaProviderModel["input"],
+		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+	{
+		id: "muse-spark-1.3-contributor",
+		name: "Muse Spark 1.3 Contributor",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		// SAFETY: Meta supports video/audio inputs, while pi-ai 0.83/0.84 types only expose text/image.
+		input: [
+			"text",
+			"image",
+			"video",
+			"audio",
+		] as unknown as MetaProviderModel["input"],
+		cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
 	{
 		id: "muse-spark-1.2",
 		name: "Muse Spark 1.2",
@@ -336,8 +386,7 @@ export async function refreshMetaToken(
 		);
 	// Pi 0.83 calls refreshToken(credentials). Pi 0.84 passes AbortSignal as
 	// the second argument. Tests inject a fetch mock in that slot.
-	const fetchImpl =
-		typeof fetchOrSignal === "function" ? fetchOrSignal : fetch;
+	const fetchImpl = typeof fetchOrSignal === "function" ? fetchOrSignal : fetch;
 	const signal = isAbortSignal(fetchOrSignal) ? fetchOrSignal : undefined;
 	if (signal?.aborted) {
 		throw new Error("Meta token refresh was cancelled");
@@ -582,6 +631,38 @@ export function metaFallbackCost(
 	return FALLBACK_MODELS.find((model) => model.id === modelId)?.cost;
 }
 
+/** Meta prompt-cache opt-in. Measured 0% hits on /chat/completions vs 93–99% on /responses with 24h. */
+export const META_PROMPT_CACHE_RETENTION = "24h";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+/**
+ * Hermes-equivalent Responses hints for api.meta.ai:
+ * setdefault `prompt_cache_retention: 24h`, and drop `reasoning.effort: none`
+ * because Meta 400s on it.
+ */
+export function applyMetaResponsesCacheHints(payload: unknown): unknown {
+	const body = asRecord(payload);
+	if (!body) return payload;
+	if (body.prompt_cache_retention === undefined) {
+		body.prompt_cache_retention = META_PROMPT_CACHE_RETENTION;
+	}
+	const reasoning = asRecord(body.reasoning);
+	if (
+		reasoning &&
+		(reasoning.effort === "none" ||
+			reasoning.effort === undefined ||
+			reasoning.effort === null)
+	) {
+		delete body.reasoning;
+	}
+	return body;
+}
+
 export function createMetaProviderConfig(): ProviderConfig {
 	return {
 		name: "Meta Model API",
@@ -614,4 +695,8 @@ export default function metaOAuthProvider(pi: ExtensionAPI): void {
 		process.env["MODEL_API_KEY"] = process.env[META_ENV_VAR];
 	}
 	pi.registerProvider(META_PROVIDER_ID, createMetaProviderConfig());
+	pi.on("before_provider_request", (event, ctx) => {
+		if (ctx.model?.provider !== META_PROVIDER_ID) return undefined;
+		return applyMetaResponsesCacheHints(event.payload);
+	});
 }

package/extensions/voice/asr.ts

@@ -53,6 +53,28 @@ export function formatAuthorization(apiKey: string): string {
 	return apiKey.startsWith("OAuth ") ? apiKey : `OAuth ${apiKey}`;
 }
 
+export function asrModel(): string {
+	return (
+		process.env.PI_META_VOICE_ASR_MODEL ??
+		process.env.MUSE_VOICE_ASR_MODEL ??
+		DEFAULT_ASR_MODEL
+	);
+}
+
+export function asrHandshake(apiKey: string): {
+	mode: "DEFAULT";
+	authorization: { accessToken: string };
+	audioEncoding: "PCM_16KHZ";
+	model: string;
+} {
+	return {
+		mode: "DEFAULT",
+		authorization: { accessToken: formatAuthorization(apiKey) },
+		audioEncoding: "PCM_16KHZ",
+		model: asrModel(),
+	};
+}
+
 export function asrEndpoint(sessionId: string): string {
 	const configured =
 		process.env.PI_META_VOICE_ASR_ENDPOINT ??
@@ -90,7 +112,9 @@ export async function socketMessageText(
 	return undefined;
 }
 
-export function parseJsonObject(text: string): Record<string, unknown> | undefined {
+export function parseJsonObject(
+	text: string,
+): Record<string, unknown> | undefined {
 	try {
 		const value = JSON.parse(text) as unknown;
 		if (value && typeof value === "object" && !Array.isArray(value)) {

package/extensions/voice.ts

@@ -11,9 +11,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
 	asrEndpoint,
+	asrHandshake,
 	chooseTranscript,
-	DEFAULT_ASR_MODEL,
-	formatAuthorization,
 	isNormalSocketClose,
 	parseJsonObject,
 	pcmAudioLevel,
@@ -25,7 +24,12 @@ import {
 	supportedPlatformLabel,
 } from "./voice/helpers.ts";
 
-export { asrEndpoint, formatAuthorization, pcmAudioLevel } from "./voice/asr.ts";
+export {
+	asrEndpoint,
+	asrHandshake,
+	formatAuthorization,
+	pcmAudioLevel,
+} from "./voice/asr.ts";
 
 const AGENT_DIR = join(homedir(), ".pi/agent");
 const SETTINGS_FILE = join(AGENT_DIR, "pi-meta-oauth-voice.json");
@@ -253,10 +257,7 @@ class MetaVoiceController {
 				this.audioLevel *= 0.78;
 			}, 120);
 			this.recordingLimitTimer = setTimeout(() => {
-				ctx.ui.notify(
-					"Voice recording reached the two-minute limit",
-					"warning",
-				);
+				ctx.ui.notify("Voice recording reached the two-minute limit", "warning");
 				this.stop(ctx);
 			}, MAX_RECORDING_MS);
 		} catch (error) {
@@ -294,17 +295,7 @@ class MetaVoiceController {
 		this.socket = socket;
 		socket.addEventListener("open", () => {
 			if (currentGeneration !== this.generation) return;
-			socket.send(
-				JSON.stringify({
-					mode: "DEFAULT",
-					authorization: { accessToken: formatAuthorization(apiKey) },
-					audioEncoding: "PCM_16KHZ",
-					model:
-						process.env.PI_META_VOICE_ASR_MODEL ??
-						process.env.MUSE_VOICE_ASR_MODEL ??
-						DEFAULT_ASR_MODEL,
-				}),
-			);
+			socket.send(JSON.stringify(asrHandshake(apiKey)));
 		});
 		socket.addEventListener("message", (event) => {
 			if (currentGeneration !== this.generation) return;
@@ -315,8 +306,7 @@ class MetaVoiceController {
 			this.fail(ctx, new Error("could not connect to Muse's Meta ASR service"));
 		});
 		socket.addEventListener("close", (event) => {
-			if (currentGeneration !== this.generation || this.phase === "idle")
-				return;
+			if (currentGeneration !== this.generation || this.phase === "idle") return;
 			if (
 				this.phase === "stopping" &&
 				this.transcript &&
@@ -328,8 +318,7 @@ class MetaVoiceController {
 			this.fail(
 				ctx,
 				new Error(
-					event.reason ||
-						`Meta ASR connection closed (${event.code || "unknown"})`,
+					event.reason || `Meta ASR connection closed (${event.code || "unknown"})`,
 				),
 			);
 		});
@@ -593,9 +582,7 @@ class MetaVoiceController {
 		this.generation += 1;
 		this.clearTimers();
 		this.closeResources();
-		ctx.ui.setEditorText(
-			combineEditorText(this.originalEditorText, transcript),
-		);
+		ctx.ui.setEditorText(combineEditorText(this.originalEditorText, transcript));
 		ctx.ui.setWidget("muse-voice", undefined);
 		this.renderIdleStatus(ctx);
 		if (transcript) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-meta-oauth",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Meta Model API OAuth provider and Muse-style voice dictation for pi",
   "keywords": [
     "pi-package",