pi-provider-utils 0.0.0

package/src/__tests__/streams.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Tests for stream and error primitives.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock pi-ai before importing the module under test
+vi.mock("@mariozechner/pi-ai", () => {
+	function createAssistantMessageEventStream() {
+		const events: unknown[] = [];
+		let done = false;
+		let resolve: (() => void) | undefined;
+		let waitPromise: Promise<void> | undefined;
+
+		const stream = {
+			push(event: unknown) {
+				if (done) return;
+				events.push(event);
+				const ev = event as { type?: string };
+				if (ev.type === "done" || ev.type === "error") {
+					done = true;
+				}
+				if (resolve) {
+					resolve();
+					resolve = undefined;
+				}
+			},
+			end() {
+				done = true;
+				if (resolve) {
+					resolve();
+					resolve = undefined;
+				}
+			},
+			async *[Symbol.asyncIterator]() {
+				let index = 0;
+				while (true) {
+					if (index < events.length) {
+						const event = events[index];
+						index++;
+						yield event;
+						const ev = event as { type?: string };
+						if (ev.type === "done" || ev.type === "error") return;
+					} else if (done) {
+						return;
+					} else {
+						waitPromise = new Promise<void>((r) => {
+							resolve = r;
+						});
+						await waitPromise;
+					}
+				}
+			},
+			_events: events,
+		};
+		return stream;
+	}
+
+	return { createAssistantMessageEventStream };
+});
+
+import type { Api, AssistantMessageEvent, Model } from "@mariozechner/pi-ai";
+import { createAssistantMessageEventStream } from "@mariozechner/pi-ai";
+import {
+	createErrorAssistantMessage,
+	createImmediateErrorStream,
+	createLinkedAbortController,
+	createTimeoutController,
+	normalizeUnknownError,
+	pipeAssistantStream,
+	pushErrorEvent,
+	rewriteProviderOnEvent,
+} from "../streams.js";
+
+function createMockModel(): Model<Api> {
+	return {
+		id: "test-model",
+		name: "Test Model",
+		api: "openai" as Api,
+		provider: "test-provider",
+		reasoning: false,
+		input: ["text"] as ("text" | "image")[],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128_000,
+		maxTokens: 16_384,
+		baseUrl: "https://api.test.com",
+	} as Model<Api>;
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// normalizeUnknownError
+// ---------------------------------------------------------------------------
+
+describe("normalizeUnknownError", () => {
+	it("extracts message from Error instances", () => {
+		expect(normalizeUnknownError(new Error("boom"))).toBe("boom");
+	});
+
+	it("returns string values as-is", () => {
+		expect(normalizeUnknownError("something failed")).toBe("something failed");
+	});
+
+	it("JSON-serializes other values", () => {
+		expect(normalizeUnknownError({ code: 500 })).toBe('{"code":500}');
+	});
+
+	it("handles null", () => {
+		expect(normalizeUnknownError(null)).toBe("null");
+	});
+
+	it("handles undefined", () => {
+		expect(normalizeUnknownError(undefined)).toBe(undefined);
+		// JSON.stringify(undefined) returns undefined
+	});
+
+	it("handles numbers", () => {
+		expect(normalizeUnknownError(42)).toBe("42");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// createErrorAssistantMessage
+// ---------------------------------------------------------------------------
+
+describe("createErrorAssistantMessage", () => {
+	it("builds a zero-usage error message", () => {
+		const model = createMockModel();
+		const msg = createErrorAssistantMessage(model, "test error");
+
+		expect(msg.role).toBe("assistant");
+		expect(msg.content).toEqual([]);
+		expect(msg.api).toBe("openai");
+		expect(msg.provider).toBe("test-provider");
+		expect(msg.model).toBe("test-model");
+		expect(msg.stopReason).toBe("error");
+		expect(msg.errorMessage).toBe("test error");
+		expect(msg.usage.totalTokens).toBe(0);
+		expect(msg.usage.cost.total).toBe(0);
+		expect(msg.timestamp).toBeGreaterThan(0);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// pushErrorEvent
+// ---------------------------------------------------------------------------
+
+describe("pushErrorEvent", () => {
+	it("pushes an error event into the stream", () => {
+		const stream = createAssistantMessageEventStream();
+		const model = createMockModel();
+
+		pushErrorEvent(stream, model, "credential missing");
+
+		const events = (stream as unknown as { _events: unknown[] })._events;
+		expect(events).toHaveLength(1);
+		const event = events[0] as { type: string; reason: string };
+		expect(event.type).toBe("error");
+		expect(event.reason).toBe("error");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// createImmediateErrorStream
+// ---------------------------------------------------------------------------
+
+describe("createImmediateErrorStream", () => {
+	it("creates a stream with a single error event", async () => {
+		const model = createMockModel();
+		const stream = createImmediateErrorStream(model, "no backend");
+
+		const collected: AssistantMessageEvent[] = [];
+		for await (const event of stream) {
+			collected.push(event as AssistantMessageEvent);
+		}
+
+		expect(collected).toHaveLength(1);
+		expect(collected[0]?.type).toBe("error");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// pipeAssistantStream
+// ---------------------------------------------------------------------------
+
+describe("pipeAssistantStream", () => {
+	it("forwards all events from source to target", async () => {
+		const source = createAssistantMessageEventStream();
+		const target = createAssistantMessageEventStream();
+
+		source.push({
+			type: "text_delta",
+			contentIndex: 0,
+			delta: "hello",
+		} as unknown as AssistantMessageEvent);
+		source.push({
+			type: "done",
+			reason: "stop",
+		} as unknown as AssistantMessageEvent);
+
+		await pipeAssistantStream(source, target);
+
+		const events = (target as unknown as { _events: unknown[] })._events;
+		expect(events).toHaveLength(2);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// rewriteProviderOnEvent
+// ---------------------------------------------------------------------------
+
+describe("rewriteProviderOnEvent", () => {
+	it("rewrites provider on partial events", () => {
+		const event: AssistantMessageEvent = {
+			type: "partial",
+			partial: { provider: "internal", content: "hi" },
+		} as unknown as AssistantMessageEvent;
+
+		const rewritten = rewriteProviderOnEvent(event, "public-provider");
+
+		expect(
+			(rewritten as { partial: { provider: string } }).partial.provider,
+		).toBe("public-provider");
+	});
+
+	it("rewrites provider on done events", () => {
+		const event: AssistantMessageEvent = {
+			type: "done",
+			message: { provider: "internal", content: "hi" },
+		} as unknown as AssistantMessageEvent;
+
+		const rewritten = rewriteProviderOnEvent(event, "public-provider");
+
+		expect(
+			(rewritten as { message: { provider: string } }).message.provider,
+		).toBe("public-provider");
+	});
+
+	it("rewrites provider on error events", () => {
+		const event: AssistantMessageEvent = {
+			type: "error",
+			reason: "error",
+			error: { provider: "internal", errorMessage: "fail" },
+		} as unknown as AssistantMessageEvent;
+
+		const rewritten = rewriteProviderOnEvent(event, "public-provider");
+
+		expect((rewritten as { error: { provider: string } }).error.provider).toBe(
+			"public-provider",
+		);
+	});
+
+	it("returns unmodified events that have no recognized shape", () => {
+		const event = {
+			type: "other",
+			data: 42,
+		} as unknown as AssistantMessageEvent;
+
+		const rewritten = rewriteProviderOnEvent(event, "public-provider");
+
+		expect(rewritten).toEqual(event);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// createLinkedAbortController
+// ---------------------------------------------------------------------------
+
+describe("createLinkedAbortController", () => {
+	it("creates a standalone controller when no signal is provided", () => {
+		const controller = createLinkedAbortController();
+		expect(controller.signal.aborted).toBe(false);
+	});
+
+	it("creates an already-aborted controller when signal is aborted", () => {
+		const parent = new AbortController();
+		parent.abort();
+
+		const linked = createLinkedAbortController(parent.signal);
+
+		expect(linked.signal.aborted).toBe(true);
+	});
+
+	it("aborts the linked controller when the parent signal fires", () => {
+		const parent = new AbortController();
+		const linked = createLinkedAbortController(parent.signal);
+
+		expect(linked.signal.aborted).toBe(false);
+		parent.abort();
+		expect(linked.signal.aborted).toBe(true);
+	});
+
+	it("does not abort the parent when the linked controller is aborted", () => {
+		const parent = new AbortController();
+		const linked = createLinkedAbortController(parent.signal);
+
+		linked.abort();
+
+		expect(parent.signal.aborted).toBe(false);
+		expect(linked.signal.aborted).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// createTimeoutController
+// ---------------------------------------------------------------------------
+
+describe("createTimeoutController", () => {
+	it("creates a linked controller with a timeout", () => {
+		const { controller, clear } = createTimeoutController(undefined, 5000);
+
+		expect(controller.signal.aborted).toBe(false);
+		clear();
+	});
+
+	it("aborts after the specified timeout", async () => {
+		const { controller, clear } = createTimeoutController(undefined, 10);
+
+		await new Promise((r) => setTimeout(r, 50));
+
+		expect(controller.signal.aborted).toBe(true);
+		clear();
+	});
+
+	it("can be cleared before timeout fires", async () => {
+		const { controller, clear } = createTimeoutController(undefined, 10);
+		clear();
+
+		await new Promise((r) => setTimeout(r, 50));
+
+		expect(controller.signal.aborted).toBe(false);
+	});
+
+	it("links to parent signal", () => {
+		const parent = new AbortController();
+		const { controller, clear } = createTimeoutController(parent.signal, 5000);
+
+		parent.abort();
+
+		expect(controller.signal.aborted).toBe(true);
+		clear();
+	});
+});

package/src/agent-paths.ts

@@ -0,0 +1,148 @@
+/**
+ * Canonical ~/.pi/agent/* path helpers and JSON file I/O.
+ *
+ * Both pi-credential-vault and pi-multicodex read and write files under
+ * the agent directory. This module provides a single, permission-aware
+ * set of helpers so path construction and file I/O are not duplicated.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a path relative to the agent directory (~/.pi/agent/).
+ *
+ * When called with no arguments, returns the agent directory itself.
+ */
+export function getAgentPath(...segments: string[]): string {
+	return join(getAgentDir(), ...segments);
+}
+
+/**
+ * Get the canonical path to the shared settings file.
+ *
+ * Returns `~/.pi/agent/settings.json`.
+ */
+export function getAgentSettingsPath(): string {
+	return getAgentPath("settings.json");
+}
+
+/**
+ * Get the canonical path to the native auth credentials file.
+ *
+ * Returns `~/.pi/agent/auth.json`.
+ */
+export function getAgentAuthPath(): string {
+	return getAgentPath("auth.json");
+}
+
+// ---------------------------------------------------------------------------
+// Directory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure the parent directory of a file path exists.
+ *
+ * Creates intermediate directories as needed with mode 0o755.
+ * No-op if the directory already exists.
+ */
+export function ensureParentDir(filePath: string): void {
+	const dir = dirname(filePath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true, mode: 0o755 });
+	}
+}
+
+/**
+ * Async variant of ensureParentDir.
+ */
+export async function ensureParentDirAsync(filePath: string): Promise<void> {
+	const dir = dirname(filePath);
+	try {
+		await stat(dir);
+	} catch {
+		await mkdir(dir, { recursive: true, mode: 0o755 });
+	}
+}
+
+// ---------------------------------------------------------------------------
+// JSON file I/O (sync)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a JSON file and return its contents as a plain object.
+ *
+ * Returns an empty object if the file does not exist, is not valid JSON,
+ * or does not contain a JSON object at the top level.
+ */
+export function readJsonObjectFile(filePath: string): Record<string, unknown> {
+	try {
+		if (!existsSync(filePath)) {
+			return {};
+		}
+		const raw = readFileSync(filePath, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return {};
+		}
+		return parsed as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Write a plain object to a JSON file.
+ *
+ * Creates parent directories if they do not exist.
+ * Uses 2-space indentation for human readability.
+ */
+export function writeJsonObjectFile(
+	filePath: string,
+	data: Record<string, unknown>,
+): void {
+	ensureParentDir(filePath);
+	writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// JSON file I/O (async)
+// ---------------------------------------------------------------------------
+
+/**
+ * Async variant of readJsonObjectFile.
+ */
+export async function readJsonObjectFileAsync(
+	filePath: string,
+): Promise<Record<string, unknown>> {
+	try {
+		const stats = await stat(filePath).catch(() => undefined);
+		if (!stats) {
+			return {};
+		}
+		const raw = await readFile(filePath, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return {};
+		}
+		return parsed as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Async variant of writeJsonObjectFile.
+ */
+export async function writeJsonObjectFileAsync(
+	filePath: string,
+	data: Record<string, unknown>,
+): Promise<void> {
+	await ensureParentDirAsync(filePath);
+	await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+}

package/src/providers.ts

@@ -0,0 +1,95 @@
+/**
+ * Provider mirror metadata and model-registry helpers.
+ *
+ * Both pi-credential-vault and pi-multicodex need to mirror existing
+ * provider configurations before installing extension-owned behavior.
+ * This module provides a single copy of that logic.
+ */
+import {
+	getApiProvider,
+	getModels,
+	getProviders,
+	type KnownProvider,
+} from "@mariozechner/pi-ai";
+
+/**
+ * Model definition shape shared by provider mirrors.
+ *
+ * Captures the subset of a pi-ai Model that extensions need when
+ * re-registering a provider via pi.registerProvider().
+ */
+export interface MirroredModelDef {
+	readonly id: string;
+	readonly name: string;
+	readonly reasoning: boolean;
+	readonly input: ReadonlyArray<"text" | "image">;
+	readonly cost: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+	};
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+}
+
+/**
+ * A snapshot of an existing provider's configuration.
+ *
+ * Contains everything an extension needs to re-register the provider
+ * with modified behavior while preserving the original models and base URL.
+ */
+export interface MirroredProvider {
+	readonly providerId: string;
+	readonly baseUrl: string;
+	readonly api: string;
+	readonly models: ReadonlyArray<MirroredModelDef>;
+	readonly hasStreamSimple: boolean;
+}
+
+/**
+ * Mirror an existing provider's configuration from pi-ai's registry.
+ *
+ * Returns undefined if the provider has no registered models.
+ */
+export function mirrorProvider(
+	providerId: KnownProvider,
+): MirroredProvider | undefined {
+	const models = getModels(providerId);
+	if (models.length === 0) {
+		return undefined;
+	}
+
+	const first = models[0];
+	if (!first) {
+		return undefined;
+	}
+
+	const baseProvider = getApiProvider(first.api);
+	const baseUrl = first.baseUrl ?? "";
+
+	return {
+		providerId,
+		baseUrl,
+		api: first.api,
+		models: models.map((m) => ({
+			id: m.id,
+			name: m.name,
+			reasoning: m.reasoning,
+			input: m.input,
+			cost: m.cost,
+			contextWindow: m.contextWindow,
+			maxTokens: m.maxTokens,
+		})),
+		hasStreamSimple: Boolean(baseProvider),
+	};
+}
+
+/**
+ * List all provider IDs that have at least one registered model.
+ *
+ * Uses pi-ai's getProviders() — no hardcoded list needed.
+ */
+export function listProviderIdsWithModels(): KnownProvider[] {
+	return getProviders().filter((id) => getModels(id).length > 0);
+}