pi-meta-oauth 0.4.3 → 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`
@@ -61,10 +62,10 @@ Audio is captured only between the two Alt+V presses and streamed as 16 kHz mono
 
 **Windows:** uses `winmm.dll` `waveIn*` via a C# helper. On first run pi tries to compile `extensions/voice/windows-audio.cs` with `csc.exe` (in-box .NET Framework) to `~/.pi/agent/bin/pi-meta-oauth-voice-v1.exe` for best performance. If no compiler is found it falls back to `extensions/voice/windows-audio.ps1` executed with `powershell.exe -ExecutionPolicy Bypass` (PowerShell 5.1 inbox, or `pwsh` 7 if present) which compiles the same capture code at runtime via `Add-Type`. No extra install is required. If recording fails, check **Settings → Privacy & security → Microphone** that access is allowed for desktop apps.
 
-Optional overrides:
+Optional overrides (the `PI_META_*` name takes precedence):
 
-- `PI_META_VOICE_ASR_ENDPOINT`
-- `PI_META_VOICE_ASR_MODEL`
+- `PI_META_VOICE_ASR_ENDPOINT` (legacy alias: `MUSE_VOICE_ASR_ENDPOINT`)
+- `PI_META_VOICE_ASR_MODEL` (legacy alias: `MUSE_VOICE_ASR_MODEL`)
 
 ## Media tools
 
@@ -87,10 +88,14 @@ 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:** 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:
 
 ```json
@@ -99,49 +104,40 @@ To scope Pi's model picker to Meta models:
 
 ### 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.
+After a successful network model refresh, the extension persists the Meta
+catalog to `~/.pi/agent/models-store.json`. External usage tools such as
+[herdr-agent-usage](https://github.com/senna-lang/herdr-agent-usage) can then
+show a percentage (for example, `⛁ 2% (24k)`) instead of only an absolute token
+count. Pi writes the cache during interactive or RPC startup, and again after
+`/login meta`. `pi --list-models meta` lists currently available models but does
+not itself trigger a network catalog refresh. The cached catalog is also used
+when Pi starts without network access.
+
+The bundled fallback uses Meta's nominal `1,048,576`-token context window. A
+cached Muse Code 0.1.0/R708.1 catalog observed on 2026-08-06 reported a lower
+effective limit of `1,007,997` for `muse-spark-1.2` and
+`muse-spark-1.2-contributor`. If you need percentages to match that specific
+Muse snapshot, you can still set `contextWindow: 1007997` for those models in
+`~/.pi/agent/models.json`; model overrides take precedence over the persisted
+catalog.
 
 ## Verify
 
 ```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/files.ts

@@ -0,0 +1,131 @@
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { META_FILES_URL } from "../meta.ts";
+import {
+	AUTOMATIC_UPLOAD_EXPIRY_SECONDS,
+	FILES_API_LIMIT_BYTES,
+} from "./limits.ts";
+import { filenameForMime, mimeForPath } from "./mime.ts";
+
+export interface UploadResult {
+	id: string;
+	filename: string;
+	bytes: number;
+	purpose: string;
+	status: string;
+	expires_at?: number;
+}
+
+function uploadErrorDetail(body: Record<string, unknown>, bodyText: string): string {
+	if (typeof body.error === "string") return body.error;
+	if (typeof body.message === "string") return body.message;
+	if (typeof body.error_description === "string") return body.error_description;
+	return bodyText.slice(0, 500);
+}
+
+export async function uploadMetaFile(
+	apiKey: string,
+	filePath: string,
+	expiresAfter?: { anchor: "created_at"; seconds: number },
+	signal?: AbortSignal,
+): Promise<UploadResult> {
+	const size = statSync(filePath).size;
+	if (size > FILES_API_LIMIT_BYTES) {
+		throw new Error(
+			`File too large for Files API (${size} bytes > 1 GiB)`,
+		);
+	}
+	const data = await readFile(filePath, { signal });
+	const mime = mimeForPath(filePath) ?? "application/octet-stream";
+	const blob = new Blob([data], { type: mime });
+	const form = new FormData();
+	form.append("file", blob, basename(filePath));
+	form.append("purpose", "user_data");
+	if (expiresAfter) {
+		form.append("expires_after[anchor]", expiresAfter.anchor);
+		form.append("expires_after[seconds]", String(expiresAfter.seconds));
+	}
+	const res = await fetch(META_FILES_URL, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${apiKey}` },
+		body: form,
+		signal,
+	});
+	const bodyText = await res.text();
+	let body: Record<string, unknown> = {};
+	try {
+		body = bodyText ? (JSON.parse(bodyText) as Record<string, unknown>) : {};
+	} catch {
+		// Non-JSON body — keep empty and use raw text for error detail
+	}
+	if (!res.ok) {
+		const detail = uploadErrorDetail(body, bodyText);
+		if (res.status === 400 && detail.includes("storage")) {
+			throw new Error(
+				`Meta Files storage limit reached (100 GiB/team). Delete old files via DELETE /v1/files/{id}. Detail: ${detail}`,
+			);
+		}
+		throw new Error(
+			`Meta Files upload failed (HTTP ${res.status}): ${detail || res.statusText}`,
+		);
+	}
+	const id =
+		typeof body.id === "string"
+			? body.id
+			: typeof body.file_id === "string"
+				? body.file_id
+				: undefined;
+	if (!id) {
+		throw new Error(
+			`Meta Files upload returned no id: ${bodyText.slice(0, 500)}`,
+		);
+	}
+	return {
+		id,
+		filename:
+			typeof body.filename === "string" ? body.filename : basename(filePath),
+		bytes: typeof body.bytes === "number" ? body.bytes : data.byteLength,
+		purpose: typeof body.purpose === "string" ? body.purpose : "user_data",
+		status: typeof body.status === "string" ? body.status : "uploaded",
+		expires_at:
+			typeof body.expires_at === "number" ? body.expires_at : undefined,
+	};
+}
+
+export async function uploadInlineMedia(
+	apiKey: string,
+	base64: string,
+	mime: string,
+	filename: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	const blob = new Blob([Buffer.from(base64, "base64")], { type: mime });
+	const form = new FormData();
+	form.append("file", blob, filename || filenameForMime(mime));
+	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}` },
+		body: form,
+		signal,
+	});
+	const text = await res.text();
+	if (!res.ok) {
+		throw new Error(
+			`Files upload for large inline media failed: ${text.slice(0, 500)}`,
+		);
+	}
+	let json: Record<string, unknown>;
+	try {
+		json = JSON.parse(text) as Record<string, unknown>;
+	} catch (error) {
+		throw new Error(`Files upload returned invalid JSON: ${String(error)}`);
+	}
+	if (typeof json.id !== "string" || !json.id) {
+		throw new Error(`Files upload returned no id: ${text.slice(0, 500)}`);
+	}
+	return json.id;
+}

package/extensions/media/limits.ts

@@ -0,0 +1,12 @@
+export const INLINE_LIMIT_BYTES = 50_000_000;
+export const FILES_API_LIMIT_BYTES = 1_073_741_824;
+// Meta Responses `store=true` (default) has ~20 MB persistence limit even when
+// inline limit is 50 MB — a 24 MB base64 payload triggers HTTP 413
+// "payload_too_large … with `store=true`". Keep inline only for small files
+// and force Files API or `store:false` above this threshold.
+export const STORE_SAFE_INLINE_BYTES = 15_000_000;
+export const AUTOMATIC_UPLOAD_EXPIRY_SECONDS = 24 * 60 * 60;
+export const EXPLICIT_UPLOAD_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+export const MIN_UPLOAD_EXPIRY_SECONDS = 3_600;
+export const MAX_UPLOAD_EXPIRY_SECONDS = 2_592_000;
+export const MAX_ANALYSIS_SOURCES = 50;

package/extensions/media/mime.ts

@@ -0,0 +1,178 @@
+import { extname } from "node:path";
+
+export interface ResponsesContentBlock {
+	type: string;
+	[key: string]: unknown;
+}
+
+type SupportedMime =
+	| "video/mp4"
+	| "audio/mpeg"
+	| "audio/wav"
+	| "application/pdf"
+	| "image/png"
+	| "image/jpeg"
+	| "image/gif"
+	| "image/webp"
+	| "image/x-icon"
+	| "text/plain"
+	| "application/json"
+	| "application/jsonl";
+
+const EXT_TO_MIME: Record<string, SupportedMime> = {
+	".mp4": "video/mp4",
+	".m4v": "video/mp4",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".pdf": "application/pdf",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".ico": "image/x-icon",
+	".txt": "text/plain",
+	".json": "application/json",
+	".jsonl": "application/jsonl",
+};
+
+export function mimeForPath(path: string): SupportedMime | undefined {
+	const ext = extname(path).toLowerCase();
+	return EXT_TO_MIME[ext];
+}
+
+export function mimeForDataUrl(dataUrl: string): string | undefined {
+	const m = dataUrl.match(/^data:([^;,\s]+)[;,]/);
+	return m?.[1]?.toLowerCase();
+}
+
+export function isVideoMime(m: string | undefined): boolean {
+	return m === "video/mp4";
+}
+
+export function isAudioMime(m: string | undefined): boolean {
+	return (
+		m === "audio/mpeg" ||
+		m === "audio/mp3" ||
+		m === "audio/wav" ||
+		m === "audio/x-wav"
+	);
+}
+
+export function isPdfMime(m: string | undefined): boolean {
+	return m === "application/pdf";
+}
+
+export function isImageMime(m: string | undefined): boolean {
+	return typeof m === "string" && m.startsWith("image/");
+}
+
+export function filenameForMime(
+	mime: string | undefined,
+	fallback = "file.bin",
+): string {
+	switch (mime) {
+		case "video/mp4":
+			return "video.mp4";
+		case "audio/mpeg":
+		case "audio/mp3":
+			return "audio.mp3";
+		case "audio/wav":
+		case "audio/x-wav":
+			return "audio.wav";
+		case "application/pdf":
+			return "document.pdf";
+		default:
+			return fallback;
+	}
+}
+
+export function audioFormatForMime(mime: string | undefined): "wav" | "mp3" {
+	return mime === "audio/wav" || mime === "audio/x-wav" ? "wav" : "mp3";
+}
+
+export function base64FromDataUrl(dataUrl: string): string {
+	const comma = dataUrl.indexOf(",");
+	return comma === -1 ? "" : dataUrl.slice(comma + 1);
+}
+
+export function base64ByteLength(base64: string): number {
+	const normalized = base64.replace(/\s/g, "");
+	if (!normalized) return 0;
+	const padding = normalized.endsWith("==")
+		? 2
+		: normalized.endsWith("=")
+			? 1
+			: 0;
+	return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
+}
+
+export function isRemoteMediaSource(source: string): boolean {
+	return source.startsWith("https://") || source.startsWith("data:");
+}
+
+export function mediaPathFromUrl(url: string): string {
+	if (url.startsWith("data:")) return url;
+	try {
+		return new URL(url).pathname;
+	} catch {
+		const withoutHash = url.split("#")[0] ?? url;
+		return withoutHash.split("?")[0] ?? withoutHash;
+	}
+}
+
+export function mimeForSource(source: string): string | undefined {
+	if (source.startsWith("data:")) return mimeForDataUrl(source);
+	if (source.startsWith("https://")) {
+		try {
+			return mimeForPath(new URL(source).pathname);
+		} catch {
+			return undefined;
+		}
+	}
+	return mimeForPath(source);
+}
+
+/** Build a generic Meta Responses input_file block. */
+export function inputFileFromSource(
+	source: string,
+	filename?: string,
+): ResponsesContentBlock {
+	if (source.startsWith("https://")) {
+		return { type: "input_file", file_url: source };
+	}
+	if (source.startsWith("data:")) {
+		const mime = mimeForDataUrl(source);
+		return {
+			type: "input_file",
+			file_data: source,
+			filename: filename ?? filenameForMime(mime),
+		};
+	}
+	return { type: "input_file", file_id: source };
+}
+
+/** Build the typed content block required by Meta for each media kind. */
+export function mediaInputFromSource(
+	source: string,
+	filename?: string,
+	expectedMime?: string,
+): ResponsesContentBlock {
+	if (!source.startsWith("data:") && !source.startsWith("https://")) {
+		return { type: "input_file", file_id: source };
+	}
+	const mime = expectedMime ?? mimeForSource(source);
+	if (isVideoMime(mime)) {
+		return { type: "input_video", video_url: source };
+	}
+	if (isAudioMime(mime) && source.startsWith("data:")) {
+		return {
+			type: "input_audio",
+			input_audio: {
+				data: base64FromDataUrl(source),
+				format: audioFormatForMime(mime),
+			},
+		};
+	}
+	return inputFileFromSource(source, filename);
+}