pi-meta-oauth 0.4.2 → 0.4.3

package/README.md

@@ -3,6 +3,7 @@
 # pi-meta-oauth
 
 <!-- markdownlint-disable-next-line MD013 -->
+![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/blockedpaths?style=flat&link=https%3A%2F%2Fx.com%2FBlockedPaths)
 [![npm version](https://img.shields.io/npm/v/pi-meta-oauth)](https://www.npmjs.com/package/pi-meta-oauth) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub stars](https://img.shields.io/github/stars/BlockedPath/pi-meta-oauth?style=social)](https://github.com/BlockedPath/pi-meta-oauth/stargazers) [![Last Commit](https://img.shields.io/github/last-commit/BlockedPath/pi-meta-oauth)](https://github.com/BlockedPath/pi-meta-oauth/commits/main) [![Issues](https://img.shields.io/github/issues/BlockedPath/pi-meta-oauth)](https://github.com/BlockedPath/pi-meta-oauth/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BlockedPath/pi-meta-oauth/pulls) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org/en/v1.0.0/) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/) [![CI](https://github.com/BlockedPath/pi-meta-oauth/actions/workflows/ci.yml/badge.svg)](https://github.com/BlockedPath/pi-meta-oauth/actions/workflows/ci.yml) [![Pi compatible](https://img.shields.io/badge/pi-Compatible-blueviolet)](https://pi.dev)
 
 Meta Model API OAuth and Muse-style voice input for [pi](https://pi.dev).
@@ -65,6 +66,21 @@ Optional overrides:
 - `PI_META_VOICE_ASR_ENDPOINT`
 - `PI_META_VOICE_ASR_MODEL`
 
+## Media tools
+
+Text-only Pi models can delegate media inspection to Muse Spark without switching models:
+
+- `meta_analyze_file` inspects one or more images, PDFs, audio files, or videos. Use ordered `sources` with optional labels for comparisons such as before and after screenshots.
+- `meta_describe_video` analyzes MP4 visuals and embedded audio.
+- `meta_transcribe_audio` transcribes MP3 or WAV speech.
+- `meta_upload_file` uploads a large or reusable file and returns a Meta `file_id`.
+
+Give each analysis tool a task-specific prompt that asks for the evidence the calling model needs next. Analysis tools default to an 8,000-token Muse generation budget and accept `max_output_tokens` from 4,000 to 32,000. Inline tool output defaults to 20,000 characters and accepts `max_chars` up to 50,000. If a result is truncated, the complete text is saved to a temporary file so the agent can continue with Pi's `read` tool using `offset` and `limit`.
+
+Automatic uploads made during analysis expire after 24 hours. Explicit `meta_upload_file` uploads expire after seven days by default; set `expires_after_seconds` to choose another supported duration or `retain: true` to keep a file without expiry.
+
+Media tool failures are reported as failed Pi tool calls, allowing the calling model to retry or report the blocker. Media analysis is model-generated observation, so verify consequential details when another source is available.
+
 ## Models
 
 Fallback models use a 1,048,576-token context window, up to 256K output tokens, image input, and reasoning levels `minimal`, `low`, `medium`, `high`, and `xhigh`.
@@ -81,6 +97,42 @@ To scope Pi's model picker to Meta models:
 { "enabledModels": ["meta/*"] }
 ```
 
+### Making context windows visible to external tools
+
+Pi knows the Meta context window at runtime, but it does **not** persist
+catalogs for extension-registered providers to `~/.pi/agent/models-store.json`.
+Anything reading Pi's session data from outside the process therefore sees no
+window for `meta` models and can only show an absolute token count.
+
+This affects usage tooling such as
+[herdr-agent-usage](https://github.com/senna-lang/herdr-agent-usage), whose
+sidebar shows `⛁ 24k` instead of `⛁ 2% (24k)` for Muse panes.
+
+To publish the window, add an override to `~/.pi/agent/models.json`:
+
+```json
+{
+  "providers": {
+    "meta": {
+      "modelOverrides": {
+        "muse-spark-1.2": { "contextWindow": 1007997 },
+        "muse-spark-1.2-contributor": { "contextWindow": 1007997 }
+      }
+    }
+  }
+}
+```
+
+`1,007,997` is the effective limit reported for those two models by a cached
+Muse Code 0.1.0/R708.1 catalog snapshot observed on 2026-08-06. That snapshot
+did not include `muse-spark-1.1`, so no effective-limit override is claimed for
+1.1 here. The bundled fallback in `extensions/meta.ts` uses the nominal
+`1048576`; use the lower value only when you want percentages to match that
+specific Muse snapshot.
+
+This only adds metadata — the provider itself is still registered by the
+extension, and `pi --list-models meta` is unchanged.
+
 ## Verify
 
 ```bash

package/extensions/media-output.ts

@@ -0,0 +1,123 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_MEDIA_MAX_CHARS = 20_000;
+export const MAX_MEDIA_MAX_CHARS = 50_000;
+export const DEFAULT_MEDIA_MAX_OUTPUT_TOKENS = 8_000;
+export const MIN_MEDIA_MAX_OUTPUT_TOKENS = 4_000;
+export const MAX_MEDIA_MAX_OUTPUT_TOKENS = 32_000;
+const MAX_INLINE_BYTES = 50 * 1024;
+const MAX_INLINE_LINES = 2_000;
+
+export interface MediaOutputDetails {
+	path?: string;
+	chars: number;
+	lines: number;
+	truncated: boolean;
+	incomplete: boolean;
+}
+
+function clampInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {
+	if (value === undefined) return fallback;
+	return Math.max(minimum, Math.min(maximum, Math.trunc(value)));
+}
+
+export function mediaMaxChars(value: number | undefined): number {
+	return clampInteger(value, DEFAULT_MEDIA_MAX_CHARS, 1_000, MAX_MEDIA_MAX_CHARS);
+}
+
+export function mediaMaxOutputTokens(value: number | undefined): number {
+	return clampInteger(
+		value,
+		DEFAULT_MEDIA_MAX_OUTPUT_TOKENS,
+		MIN_MEDIA_MAX_OUTPUT_TOKENS,
+		MAX_MEDIA_MAX_OUTPUT_TOKENS,
+	);
+}
+
+function inlineSlice(text: string, maxChars: number): string {
+	let slice = text.split("\n").slice(0, MAX_INLINE_LINES).join("\n").slice(0, maxChars);
+	if (Buffer.byteLength(slice, "utf8") <= MAX_INLINE_BYTES) return slice;
+	const bytes = Buffer.from(slice, "utf8").subarray(0, MAX_INLINE_BYTES);
+	slice = new TextDecoder().decode(bytes);
+	return slice.endsWith("\uFFFD") ? slice.slice(0, -1) : slice;
+}
+
+function responseReason(response: unknown): string | undefined {
+	if (!response || typeof response !== "object") return undefined;
+	const record = response as Record<string, unknown>;
+	const details = record.incomplete_details;
+	if (details && typeof details === "object") {
+		const reason = (details as Record<string, unknown>).reason;
+		if (typeof reason === "string") return reason;
+	}
+	for (const key of ["finish_reason", "stop_reason"]) {
+		if (typeof record[key] === "string") return record[key] as string;
+	}
+	return record.status === "incomplete" ? "incomplete" : undefined;
+}
+
+export function responseHitOutputLimit(response: unknown): boolean {
+	const reason = responseReason(response)?.toLowerCase();
+	return reason === "max_output_tokens" || reason === "length" || reason === "max_tokens";
+}
+
+function outputFilePath(identity: string, text: string): string {
+	const hash = createHash("sha256").update(`${identity}\0${text.length}\0${text.slice(0, 1024)}`).digest("hex").slice(0, 16);
+	return join(tmpdir(), `pi-meta-media-${hash}.txt`);
+}
+
+async function saveFullOutput(identity: string, text: string): Promise<string | undefined> {
+	const basePath = outputFilePath(identity, text);
+	try {
+		await mkdir(tmpdir(), { recursive: true });
+		try {
+			await writeFile(basePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+			return basePath;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			const uniquePath = `${basePath}.${randomBytes(4).toString("hex")}`;
+			await writeFile(uniquePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+			return uniquePath;
+		}
+	} catch {
+		return undefined;
+	}
+}
+
+export async function prepareMediaOutput(options: {
+	text: string;
+	identity: string;
+	maxChars?: number;
+	response?: unknown;
+}): Promise<{ text: string; details: MediaOutputDetails }> {
+	const { text, identity, response } = options;
+	const slice = inlineSlice(text, mediaMaxChars(options.maxChars));
+	const truncated = slice.length < text.length;
+	const lines = text.length === 0 ? 0 : text.split("\n").length;
+	const incomplete = responseHitOutputLimit(response);
+	const savedPath = truncated ? await saveFullOutput(identity, text) : undefined;
+	const notes: string[] = [];
+	if (truncated) {
+		notes.push(
+			savedPath
+				? `content truncated at ${slice.length} of ${text.length} characters; full content saved to: ${savedPath} (${lines} lines). Use the read tool with offset/limit to continue (offset is a 1-based line number).`
+				: `content truncated at ${slice.length} of ${text.length} characters; the full content could not be saved, so continuation is unavailable.`,
+		);
+	}
+	if (incomplete) {
+		notes.push("Muse exhausted max_output_tokens, so the analysis may be incomplete. Retry with a larger budget or a narrower prompt.");
+	}
+	return {
+		text: `${slice}${notes.length > 0 ? `\n\n[${notes.join(" ")}]` : ""}`,
+		details: {
+			...(savedPath ? { path: savedPath } : {}),
+			chars: text.length,
+			lines,
+			truncated,
+			incomplete,
+		},
+	};
+}

package/extensions/media.ts

@@ -13,6 +13,15 @@ import {
 import { existsSync, statSync, readFileSync } from "node:fs";
 import { basename, extname, resolve } from "node:path";
 import { readFile } from "node:fs/promises";
+import {
+	DEFAULT_MEDIA_MAX_CHARS,
+	DEFAULT_MEDIA_MAX_OUTPUT_TOKENS,
+	MAX_MEDIA_MAX_CHARS,
+	MAX_MEDIA_MAX_OUTPUT_TOKENS,
+	MIN_MEDIA_MAX_OUTPUT_TOKENS,
+	mediaMaxOutputTokens,
+	prepareMediaOutput,
+} from "./media-output.ts";
 
 // ---------------------------------------------------------------------------
 // Meta Files API + Responses API
@@ -34,6 +43,11 @@ const FILES_API_LIMIT_BYTES = 1_073_741_824;
 // "payload_too_large … with `store=true`". Keep inline only for small files
 // and force Files API or `store:false` above this threshold.
 const STORE_SAFE_INLINE_BYTES = 15_000_000;
+const AUTOMATIC_UPLOAD_EXPIRY_SECONDS = 24 * 60 * 60;
+const EXPLICIT_UPLOAD_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+const MIN_UPLOAD_EXPIRY_SECONDS = 3_600;
+const MAX_UPLOAD_EXPIRY_SECONDS = 2_592_000;
+const MAX_ANALYSIS_SOURCES = 50;
 
 type SupportedMime =
 	| "video/mp4"
@@ -613,6 +627,48 @@ function dataUrlForFile(path: string): {
 	};
 }
 
+type AnalysisSource = { source: string; label?: string };
+
+const automaticExpiry = () => ({
+	anchor: "created_at" as const,
+	seconds: AUTOMATIC_UPLOAD_EXPIRY_SECONDS,
+});
+
+function mediaToolError(tool: string, error: unknown): never {
+	if (error instanceof Error && error.name === "AbortError") throw error;
+	const message = error instanceof Error ? error.message : String(error);
+	throw new Error(`${tool} failed: ${message}`, { cause: error });
+}
+
+async function resolveGenericMediaSource(
+	apiKey: string,
+	cwd: string,
+	source: string,
+): Promise<ResponsesContentBlock> {
+	if (/^file-[a-zA-Z0-9_-]+$/.test(source)) {
+		return { type: "input_file", file_id: source };
+	}
+	if (source.startsWith("https://") || source.startsWith("data:")) {
+		return mediaInputFromSource(source);
+	}
+	const absolute = resolve(cwd, source.replace(/^@/, ""));
+	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): ${source}`);
+	}
+	if (stat.size > STORE_SAFE_INLINE_BYTES) {
+		const upload = await uploadMetaFile(apiKey, absolute, automaticExpiry());
+		return { type: "input_file", file_id: upload.id };
+	}
+	const { dataUrl, mime } = dataUrlForFile(absolute);
+	return mediaInputFromSource(dataUrl, basename(absolute), mime);
+}
+
+function sourceLabel(source: AnalysisSource, index: number): string {
+	return source.label?.trim() || `Source ${index + 1}`;
+}
+
 // ---------------------------------------------------------------------------
 // Before-provider-request rewrite (Option B)
 // Makes @video.mp4 / @audio.wav / @doc.pdf work transparently even though
@@ -770,6 +826,8 @@ async function uploadInlineMedia(
 	const form = new FormData();
 	form.append("file", blob, filename);
 	form.append("purpose", "user_data");
+	form.append("expires_after[anchor]", "created_at");
+	form.append("expires_after[seconds]", String(AUTOMATIC_UPLOAD_EXPIRY_SECONDS));
 	const res = await fetch(META_FILES_URL, {
 		method: "POST",
 		headers: { Authorization: `Bearer ${apiKey}` },
@@ -1050,133 +1108,77 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		name: "meta_describe_video",
 		label: "Meta Video Describe",
 		description:
-			"Analyze an MP4 video with Muse Spark — summarizes visuals and transcribes embedded speech in one call. Provide a local path, public https URL, or existing file_id (from Files API). Handles Files API upload for large files and inline data URLs for small files. Use for: describe what happens in a clip, answer questions about footage, extract structured details. Video without audio (screen recordings) is also valid. Supports 50MB inline, 1GiB via Files API.",
-		parameters: Type.Object({
-			path: Type.Optional(
-				Type.String({
-					description:
-						"Local .mp4/.m4v file path (relative to cwd or absolute)",
-				}),
-			),
-			url: Type.Optional(
-				Type.String({
-					description:
-						"Public https:// URL or data:video/mp4;base64,... URL (skips upload)",
-				}),
-			),
-			file_id: Type.Optional(
-				Type.String({
-					description:
-						"Existing Files API id like file-842549258569145 (skips upload)",
-				}),
-			),
-			prompt: Type.String({
-				description:
-					"What to ask about the video (e.g. 'Describe what happens', 'Transcribe speech and list action items')",
-			}),
-			model: Type.Optional(
-				Type.String({ description: "Muse model id, default muse-spark-1.2" }),
-			),
-			max_output_tokens: Type.Optional(
-				Type.Number({
-					description:
-						"Default 4000 — reasoning shares budget, lower values can return empty with finish_reason:length",
-				}),
-			),
-		}),
+			"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",
+		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.",
+			"When a Meta media result is truncated, continue from its saved temp file with read using offset/limit.",
+		],
+		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}`,
+				})),
+			},
+			{ additionalProperties: false },
+		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, prompt, model, max_output_tokens } =
-				params as {
-					path?: string;
-					url?: string;
-					file_id?: string;
-					prompt: string;
-					model?: string;
-					max_output_tokens?: number;
-				};
-			if (!path && !url && !file_id) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "Provide one of: path (local .mp4), url (https://...), or file_id (file-...).",
-						},
-					],
-					details: { error: "missing source" },
-				};
+			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");
 			}
 			try {
-				const apiKey = await safeGetMetaApiKey(
-					ctx as unknown as ExtensionContext,
-				);
+				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
 				let videoBlock: ResponsesContentBlock;
-				if (file_id) {
-					videoBlock = { type: "input_file", file_id };
-				} else if (url) {
-					videoBlock = mediaInputFromSource(url, "video.mp4", "video/mp4");
-				} else if (path) {
-					const absolute = resolve(
-						(ctx as unknown as { cwd?: string }).cwd ?? process.cwd(),
-						path,
-					);
-					if (!existsSync(absolute))
-						throw new Error(`File not found: ${absolute}`);
+				if (file_id) videoBlock = { type: "input_file", file_id };
+				else if (url) videoBlock = mediaInputFromSource(url, "video.mp4", "video/mp4");
+				else {
+					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}`);
-					// Docs recommend Files API (upload → file_id) for video. Inline
-					// base64 also hits the ~20 MB `store=true` persistence limit
-					// (24 MB → HTTP 413) even when under the 50 MB inline cap.
-					// Use Files API for any video above the store-safe threshold
-					// and for all larger media; keep inline only for tiny files.
-					const useFilesApi = stat.size > STORE_SAFE_INLINE_BYTES;
-					if (useFilesApi) {
-						const up = await uploadMetaFile(apiKey, absolute);
-						videoBlock = { type: "input_file", file_id: up.id };
+					if (stat.size > FILES_API_LIMIT_BYTES) throw new Error(`File too large (1 GiB limit): ${path}`);
+					if (stat.size > STORE_SAFE_INLINE_BYTES) {
+						const upload = await uploadMetaFile(apiKey, absolute, automaticExpiry());
+						videoBlock = { type: "input_file", file_id: upload.id };
 					} else {
-						const { dataUrl } = dataUrlForFile(absolute);
-						videoBlock = mediaInputFromSource(
-							dataUrl,
-							basename(absolute),
-							"video/mp4",
-						);
+						videoBlock = mediaInputFromSource(dataUrlForFile(absolute).dataUrl, basename(absolute), "video/mp4");
 					}
-				} else {
-					throw new Error("No source");
 				}
 				const selectedModel = model ?? "muse-spark-1.2";
-				const payload: Record<string, unknown> = {
+				const { text, raw } = await callMetaResponses(apiKey, {
 					model: selectedModel,
 					store: false,
-					input: [
-						{
-							type: "message",
-							role: "user",
-							content: [
-								{ type: "input_text", text: prompt },
-								videoBlock as unknown as Record<string, unknown>,
-							],
-						},
-					],
-					max_output_tokens: Math.max(max_output_tokens ?? 8000, 4000),
-				};
-				const { text, raw } = await callMetaResponses(apiKey, payload, signal);
+					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 }],
-					details: { raw, videoBlock, usage },
+					content: [{ type: "text", text: output.text }],
+					details: { raw, videoBlock, ...output.details },
 					usage,
 				};
-			} catch (e) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Video analysis failed: ${e instanceof Error ? e.message : String(e)}`,
-						},
-					],
-					details: { error: String(e) },
-				};
+			} catch (error) {
+				mediaToolError("Video analysis", error);
 			}
 		},
 	});
@@ -1185,113 +1187,80 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		name: "meta_transcribe_audio",
 		label: "Meta Audio Transcribe",
 		description:
-			"Transcribe speech from a standalone audio file (wav, mp3) via Muse Spark. Provide local path, public URL, or file_id. Handles Files API for large files, inline base64 for small. Tip: always use max_output_tokens ≥4000 and stream for long clips to avoid empty length finish.",
-		parameters: Type.Object({
-			path: Type.Optional(Type.String({ description: "Local .wav/.mp3 path" })),
-			url: Type.Optional(
-				Type.String({ description: "Public https:// URL to audio" }),
-			),
-			file_id: Type.Optional(Type.String({ description: "Existing file_id" })),
-			prompt: Type.Optional(
-				Type.String({
-					description:
-						"Custom prompt, default 'Transcribe this audio. Return only the transcript.'",
-				}),
-			),
-			model: Type.Optional(
-				Type.String({ description: "Model id, default muse-spark-1.2" }),
-			),
-		}),
+			"Transcribe MP3 or WAV audio with Muse Spark from a local path, public URL, or Meta file_id. Results are capped by max_chars; when truncated, the full transcript is saved to a temp file for continuation with read offset/limit.",
+		promptSnippet: "Transcribe audio when the active model cannot",
+		promptGuidelines: [
+			"Use meta_transcribe_audio when the task depends on MP3 or WAV speech the active model cannot inspect directly.",
+			"When a Meta media result is truncated, continue from its saved temp file with read using offset/limit.",
+		],
+		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}`,
+				})),
+			},
+			{ additionalProperties: false },
+		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, prompt, model } = params as {
-				path?: string;
-				url?: string;
-				file_id?: string;
-				prompt?: string;
-				model?: string;
+			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) {
-				return {
-					content: [
-						{ type: "text", text: "Provide path, url, or file_id for audio." },
-					],
-					details: { error: "missing source" },
-				};
+			if ([path, url, file_id].filter(Boolean).length !== 1) {
+				throw new Error("meta_transcribe_audio requires exactly one of path, url, or file_id");
 			}
 			try {
-				const apiKey = await safeGetMetaApiKey(
-					ctx as unknown as ExtensionContext,
-				);
+				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
 				let audioBlock: ResponsesContentBlock;
-				if (file_id) {
-					audioBlock = { type: "input_file", file_id };
-				} else if (url) {
-					audioBlock = mediaInputFromSource(url, "audio.bin");
-				} else if (path) {
-					const absolute = resolve(
-						(ctx as unknown as { cwd?: string }).cwd ?? process.cwd(),
-						path,
-					);
-					if (!existsSync(absolute))
-						throw new Error(`File not found: ${absolute}`);
+				if (file_id) audioBlock = { type: "input_file", file_id };
+				else if (url) audioBlock = mediaInputFromSource(url, "audio.bin");
+				else {
+					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);
-					if (!isAudioMime(mime) && mime !== undefined) {
-						throw new Error(
-							`Unsupported audio mime ${mime}, need audio/wav or audio/mpeg`,
-						);
+					if (mime !== undefined && !isAudioMime(mime)) {
+						throw new Error(`Unsupported audio type for ${path}; use MP3 or WAV`);
 					}
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const up = await uploadMetaFile(apiKey, absolute);
-						audioBlock = { type: "input_file", file_id: up.id };
+						const upload = await uploadMetaFile(apiKey, absolute, automaticExpiry());
+						audioBlock = { type: "input_file", file_id: upload.id };
 					} else {
-						const { dataUrl } = dataUrlForFile(absolute);
-						audioBlock = mediaInputFromSource(
-							dataUrl,
-							basename(absolute),
-							mime,
-						);
+						audioBlock = mediaInputFromSource(dataUrlForFile(absolute).dataUrl, basename(absolute), mime);
 					}
-				} else {
-					throw new Error("No audio source");
 				}
-				const payload: Record<string, unknown> = {
-					model: model ?? "muse-spark-1.2",
+				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 unknown as Record<string, unknown>,
-							],
-						},
-					],
-					max_output_tokens: 4000,
-				};
-				const { text, raw } = await callMetaResponses(apiKey, payload, signal);
-				return {
-					content: [{ type: "text", text }],
-					details: { raw, audioBlock },
-				};
-			} catch (e) {
+					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: `Audio transcription failed: ${e instanceof Error ? e.message : String(e)}`,
-						},
-					],
-					details: { error: String(e) },
+					content: [{ type: "text", text: output.text }],
+					details: { raw, audioBlock, ...output.details },
+					usage,
 				};
+			} catch (error) {
+				mediaToolError("Audio transcription", error);
 			}
 		},
 	});
@@ -1300,63 +1269,46 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		name: "meta_upload_file",
 		label: "Meta Files Upload",
 		description:
-			"Upload a file to Meta Files API (POST /v1/files purpose=user_data) for reuse across video/image/pdf/audio requests. Returns file_id to use with input_file/file_id. Supports 1 GiB limit, 100 GiB/team storage. Set expires_after for auto-expiry (3600..2592000 seconds). Use for large or reused files; small one-offs can use inline data URLs.",
-		parameters: Type.Object({
-			path: Type.String({
-				description:
-					"Local file path to upload (mp4, wav, mp3, pdf, png, jpg, etc.)",
-			}),
-			expires_after_seconds: Type.Optional(
-				Type.Number({
-					description:
-						"Auto-expire after seconds (3600..2592000), default no expiry",
-				}),
-			),
-		}),
-		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, expires_after_seconds } = params as {
-				path: string;
-				expires_after_seconds?: number;
+			"Upload a local file to Meta Files API for reuse. Uploads expire after seven days by default. Set expires_after_seconds to choose 3600..2592000 seconds, or retain=true to opt into no expiry.",
+		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" })),
+			},
+			{ 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;
 			};
+			if (retain && expires_after_seconds !== undefined) {
+				throw new Error("meta_upload_file accepts either retain=true or expires_after_seconds, not both");
+			}
 			try {
-				const apiKey = await safeGetMetaApiKey(
-					ctx as unknown as ExtensionContext,
-				);
-				const absolute = resolve(
-					(ctx as unknown as { cwd?: string }).cwd ?? process.cwd(),
-					path,
-				);
-				if (!existsSync(absolute))
-					throw new Error(`File not found: ${absolute}`);
-				let expiresAfter: { anchor: "created_at"; seconds: number } | undefined;
-				if (expires_after_seconds !== undefined) {
-					if (expires_after_seconds < 3600 || expires_after_seconds > 2592000)
-						throw new Error("expires_after_seconds must be 3600..2592000");
-					expiresAfter = {
-						anchor: "created_at",
-						seconds: expires_after_seconds,
-					};
-				}
+				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 result = await uploadMetaFile(apiKey, absolute, expiresAfter);
+				const retention = retain
+					? "retained without expiry"
+					: result.expires_at
+						? `expires_at ${result.expires_at}`
+						: `expires after ${expiresAfter?.seconds} seconds`;
 				return {
-					content: [
-						{
-							type: "text",
-							text: `Uploaded ${basename(absolute)} → ${result.id} (${result.bytes} bytes, status: ${result.status}${result.expires_at ? `, expires_at: ${result.expires_at}` : ""}). Use with {type:"input_file", file_id:"${result.id}"}.`,
-						},
-					],
+					content: [{ type: "text", text: `Uploaded ${basename(absolute)} to ${result.id} (${result.bytes} bytes, ${retention}).` }],
 					details: result,
 				};
-			} catch (e) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Upload failed: ${e instanceof Error ? e.message : String(e)}`,
-						},
-					],
-					details: { error: String(e) },
-				};
+			} catch (error) {
+				mediaToolError("File upload", error);
 			}
 		},
 	});
@@ -1365,85 +1317,79 @@ export default function metaMedia(pi: ExtensionAPI): void {
 		name: "meta_analyze_file",
 		label: "Meta File Analyze",
 		description:
-			"Analyze any supported file (image, pdf, video, audio) via Muse Spark using the Files API or inline. PDFs: text first 100 pages + images first 50 pages (counts to 50-image budget). Images: up to 50/request. For generic 'summarize this document' use this; for video/audio with specific prompts use the dedicated video/audio tools.",
-		parameters: Type.Object({
-			path: Type.Optional(Type.String({ description: "Local file path" })),
-			url: Type.Optional(Type.String({ description: "Public https:// URL" })),
-			file_id: Type.Optional(Type.String({ description: "Existing file_id" })),
-			prompt: Type.String({ description: "What to ask about the file" }),
-			model: Type.Optional(
-				Type.String({ description: "Model id, default muse-spark-1.2" }),
-			),
-		}),
+			"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",
+		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.",
+			"When a Meta media result is truncated, continue from its saved temp file with read using offset/limit.",
+		],
+		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",
+				})),
+				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}`,
+				})),
+			},
+			{ additionalProperties: false },
+		),
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { path, url, file_id, prompt, model } = params as {
-				path?: string;
-				url?: string;
-				file_id?: string;
-				prompt: string;
-				model?: string;
+			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;
 			};
-			if (!path && !url && !file_id) {
-				return {
-					content: [{ type: "text", text: "Provide path, url, or file_id." }],
-					details: { error: "missing source" },
-				};
+			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`);
 			}
 			try {
-				const apiKey = await safeGetMetaApiKey(
-					ctx as unknown as ExtensionContext,
-				);
-				let fileBlock: ResponsesContentBlock;
-				if (file_id) fileBlock = { type: "input_file", file_id };
-				else if (url) fileBlock = mediaInputFromSource(url);
-				else if (path) {
-					const absolute = resolve(
-						(ctx as unknown as { cwd?: string }).cwd ?? process.cwd(),
-						path,
-					);
-					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)`);
-					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const up = await uploadMetaFile(apiKey, absolute);
-						fileBlock = { type: "input_file", file_id: up.id };
-					} else {
-						const { dataUrl, mime } = dataUrlForFile(absolute);
-						fileBlock = mediaInputFromSource(dataUrl, basename(absolute), mime);
+				const apiKey = await safeGetMetaApiKey(ctx as ExtensionContext);
+				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)}:` });
 					}
-				} else throw new Error("No source");
-				const payload: Record<string, unknown> = {
-					model: model ?? "muse-spark-1.2",
+					content.push(await resolveGenericMediaSource(apiKey, ctx.cwd, item.source));
+				}
+				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 },
-								fileBlock as unknown as Record<string, unknown>,
-							],
-						},
-					],
-					max_output_tokens: 4000,
-				};
-				const { text, raw } = await callMetaResponses(apiKey, payload, signal);
-				return {
-					content: [{ type: "text", text }],
-					details: { raw, fileBlock },
-				};
-			} catch (e) {
+					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: `File analysis failed: ${e instanceof Error ? e.message : String(e)}`,
-						},
-					],
-					details: { error: String(e) },
+					content: [{ type: "text", text: output.text }],
+					details: { raw, sourceCount: requestedSources.length, ...output.details },
+					usage,
 				};
+			} catch (error) {
+				mediaToolError("File analysis", error);
 			}
 		},
 	});
@@ -1495,7 +1441,7 @@ export default function metaMedia(pi: ExtensionAPI): void {
 					if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
 					const stat = statSync(abs);
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const up = await uploadMetaFile(apiKey, abs);
+						const up = await uploadMetaFile(apiKey, abs, automaticExpiry());
 						block = { type: "input_file", file_id: up.id };
 					} else {
 						const { dataUrl } = dataUrlForFile(abs);
@@ -1569,7 +1515,7 @@ export default function metaMedia(pi: ExtensionAPI): void {
 					if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
 					const stat = statSync(abs);
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const up = await uploadMetaFile(apiKey, abs);
+						const up = await uploadMetaFile(apiKey, abs, automaticExpiry());
 						block = { type: "input_file", file_id: up.id };
 					} else {
 						const { dataUrl, mime } = dataUrlForFile(abs);
@@ -1637,7 +1583,7 @@ export default function metaMedia(pi: ExtensionAPI): void {
 					if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
 					const stat = statSync(abs);
 					if (stat.size > STORE_SAFE_INLINE_BYTES) {
-						const up = await uploadMetaFile(apiKey, abs);
+						const up = await uploadMetaFile(apiKey, abs, automaticExpiry());
 						block = { type: "input_file", file_id: up.id };
 					} else {
 						const { dataUrl, mime } = dataUrlForFile(abs);

package/extensions/meta.ts

@@ -14,6 +14,7 @@ export const META_MODEL_CATALOG_URL = "https://api.meta.ai/v1/models";
 export const META_AUTH_BASE_URL = "https://auth.meta.com";
 export const META_CLIENT_ID = "1031625952748946";
 export const META_FILES_URL = `${META_API_BASE_URL}/files`;
+const META_ENV_VAR = "META_API_KEY";
 
 const DEVICE_AUTHORIZATION_URL = `${META_AUTH_BASE_URL}/oidc/device/authorization/`;
 const DEVICE_TOKEN_URL = `${META_AUTH_BASE_URL}/oidc/device/token/`;
@@ -339,7 +340,7 @@ function numericCost(value: unknown, fallback: number): number {
 	const number =
 		typeof value === "number"
 			? value
-			: typeof value === "string"
+			: typeof value === "string" && value.trim()
 				? Number(value)
 				: Number.NaN;
 	return Number.isFinite(number) && number >= 0 ? number : fallback;
@@ -462,6 +463,7 @@ export function createMetaProviderConfig(): ProviderConfig {
 		name: "Meta Model API",
 		baseUrl: META_API_BASE_URL,
 		api: "openai-responses",
+		apiKey: "$META_API_KEY",
 		models: [...FALLBACK_MODELS],
 		refreshModels: refreshMetaModels,
 		oauth: {
@@ -474,5 +476,18 @@ export function createMetaProviderConfig(): ProviderConfig {
 }
 
 export default function metaOAuthProvider(pi: ExtensionAPI): void {
+	// Allow MODEL_API_KEY as fallback for API-key users — shim to META_API_KEY so $META_API_KEY interpolation works.
+	if (
+		process.env[META_ENV_VAR] === undefined &&
+		process.env["MODEL_API_KEY"] !== undefined
+	) {
+		process.env[META_ENV_VAR] = process.env["MODEL_API_KEY"];
+	}
+	if (
+		process.env["MODEL_API_KEY"] === undefined &&
+		process.env[META_ENV_VAR] !== undefined
+	) {
+		process.env["MODEL_API_KEY"] = process.env[META_ENV_VAR];
+	}
 	pi.registerProvider(META_PROVIDER_ID, createMetaProviderConfig());
 }

package/extensions/voice/macos-audio.swift

@@ -73,22 +73,12 @@ private final class MicrophoneSession {
         }
         let tapBufferSize = AVAudioFrameCount(inputFormat.sampleRate * 0.1)
         do {
-            if #available(macOS 27.0, *) {
-                try inputNode.__installTap(
-                    onBus: 0,
-                    bufferSize: tapBufferSize,
-                    format: inputFormat,
-                    error: (),
-                    block: tap
-                )
-            } else {
-                inputNode.installTap(
-                    onBus: 0,
-                    bufferSize: tapBufferSize,
-                    format: inputFormat,
-                    block: tap
-                )
-            }
+            inputNode.installTap(
+                onBus: 0,
+                bufferSize: tapBufferSize,
+                format: inputFormat,
+                block: tap
+            )
             audioEngine.prepare()
             try audioEngine.start()
         } catch {

package/package.json

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