@centerforagenticai/pi-multi-account 0.1.1 → 0.1.4

package/src/openai-adapter.ts

@@ -12,15 +12,21 @@
  *
  * Catalog source is capture-or-compose: the live model registry's base `openai`
  * provider catalog when the host has registered it (the pinned Pi 0.84.4 ships
- * it), else the pinned `@earendil-works/pi-ai` `openaiProvider()` factory. Base
- * providers are only read, never mutated or re-registered.
+ * it), else the pinned `@earendil-works/pi-ai` built-in `openai` catalog (the
+ * same `OPENAI_MODELS` the `openaiProvider()` factory wraps). Base providers are
+ * only read, never mutated or re-registered.
+ *
+ * The built-in catalog is read through `@earendil-works/pi-ai/providers/all`,
+ * not `@earendil-works/pi-ai/providers/openai`: Pi's extension loader aliases
+ * only the pi-ai root, `/compat`, `/oauth` and `/providers/all`, so any other
+ * pi-ai subpath resolves under the aliased root file and fails extension load.
  */
 
 import type {
 	ProviderConfig,
 	ProviderModelConfig,
 } from "@earendil-works/pi-coding-agent";
-import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
 import { cloneProviderModelCatalog } from "./catalog-rebinding.js";
 
 /** pi-ai model API id for the OpenAI platform Responses API. */
@@ -45,7 +51,7 @@ export class OpenAiAdapterContractError extends Error {
 /**
  * Model configs for the OpenAI platform catalog, deeply isolated from any
  * registry-owned object. Prefers the live registry's base `openai` catalog;
- * falls back to the pinned pi-ai `openaiProvider()` factory when the host has
+ * falls back to the pinned pi-ai built-in `openai` catalog when the host has
  * not registered a base `openai` provider. The registry-owned `provider`
  * identity is stripped so the caller can re-point each model at the alias id.
  */
@@ -70,11 +76,15 @@ function tryCaptureRegistryModels(
 }
 
 function composeModelsFromFactory(): readonly ProviderModelConfig[] {
-	const provider = openaiProvider();
-	const models = provider.getModels();
-	if (models.length === 0) {
+	if (typeof getBuiltinModels !== "function") {
+		throw new OpenAiAdapterContractError(
+			"The pinned pi-ai providers/all entry no longer exports getBuiltinModels.",
+		);
+	}
+	const models: unknown = getBuiltinModels(OPENAI_BASE_PROVIDER);
+	if (!Array.isArray(models) || models.length === 0) {
 		throw new OpenAiAdapterContractError(
-			"The pinned pi-ai openai provider factory yielded no models.",
+			"The pinned pi-ai built-in openai catalog yielded no models.",
 		);
 	}
 	return models.map((model: unknown) => {

package/src/pi-ai-entrypoints.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
+import { CodexContractError } from "./codex-adapter.js";
+
+/**
+ * Host boundary: Pi's extension loader aliases only the pi-ai root, `/compat`,
+ * `/oauth` and `/providers/all`. Every other `@earendil-works/pi-ai/<subpath>`
+ * resolves beneath the aliased root file (`dist/compat.js/<subpath>`) and
+ * cannot load, so entries here try loader-safe specifiers first and keep any
+ * other subpath behind a guarded fallback for plain Node. See UPSTREAM.md.
+ */
+
+type StreamSimple = NonNullable<ProviderConfig["streamSimple"]>;
+
+/** pi-ai specifiers the Codex stream resolver may import. */
+export type CodexStreamSpecifier =
+	| "@earendil-works/pi-ai"
+	| "@earendil-works/pi-ai/api/openai-codex-responses"
+	| "@earendil-works/pi-ai/compat";
+
+export type ModuleImporter = (specifier: CodexStreamSpecifier) => Promise<unknown>;
+
+// Literal specifiers keep the imports visible to Pi's loader and to bundlers.
+const defaultImporter: ModuleImporter = (specifier) => {
+	switch (specifier) {
+		case "@earendil-works/pi-ai":
+			return import("@earendil-works/pi-ai");
+		case "@earendil-works/pi-ai/api/openai-codex-responses":
+			return import("@earendil-works/pi-ai/api/openai-codex-responses");
+		case "@earendil-works/pi-ai/compat":
+			return import("@earendil-works/pi-ai/compat");
+	}
+};
+
+function field(module: unknown, key: string): unknown {
+	return module !== null && typeof module === "object"
+		? (module as Record<string, unknown>)[key]
+		: undefined;
+}
+
+/**
+ * Resolves the maintained pi-ai Codex Responses stream, in order:
+ * 1. the public root's legacy `streamSimpleOpenAICodexResponses` (present when
+ *    Pi's loader aliases the root to `dist/compat.js`);
+ * 2. `api/openai-codex-responses` `streamSimple`, guarded (plain Node only);
+ * 3. `/compat` `streamSimpleOpenAICodexResponses`, then
+ *    `openAICodexResponsesApi().streamSimple`.
+ * Fails closed with {@link CodexContractError} when none yields a function.
+ */
+export async function loadMaintainedCodexStream(
+	importModule: ModuleImporter = defaultImporter,
+): Promise<StreamSimple> {
+	const root = await importModule("@earendil-works/pi-ai");
+	const rootStream = field(root, "streamSimpleOpenAICodexResponses");
+	if (typeof rootStream === "function") return rootStream as StreamSimple;
+	try {
+		const maintained = field(
+			await importModule("@earendil-works/pi-ai/api/openai-codex-responses"),
+			"streamSimple",
+		);
+		if (typeof maintained === "function") return maintained as StreamSimple;
+	} catch {
+		// Not resolvable under Pi's aliased loader; try the compat entry.
+	}
+	try {
+		const compat = await importModule("@earendil-works/pi-ai/compat");
+		const legacy = field(compat, "streamSimpleOpenAICodexResponses");
+		if (typeof legacy === "function") return legacy as StreamSimple;
+		const factory = field(compat, "openAICodexResponsesApi");
+		if (typeof factory === "function") {
+			const lazy = field((factory as () => unknown)(), "streamSimple");
+			if (typeof lazy === "function") return lazy as StreamSimple;
+		}
+	} catch {
+		// Fall through to the fail-closed contract error.
+	}
+	throw new CodexContractError(
+		"No pi-ai entry exposes the maintained openai-codex-responses streamSimple.",
+	);
+}
+
+export interface PiAiVersionSources {
+	readonly resolve: (specifier: string) => string;
+	readonly readFile: (path: string) => string;
+}
+
+const defaultVersionSources: PiAiVersionSources = {
+	resolve: (specifier) => import.meta.resolve(specifier),
+	readFile: (path) => readFileSync(path, "utf-8"),
+};
+
+/**
+ * Resolves the installed `@earendil-works/pi-ai` version by walking up from
+ * its resolved `/compat` (then root) entry to the nearest `package.json`
+ * named `@earendil-works/pi-ai`. Local, bounded and offline. Returns
+ * `pi-ai@unknown` when neither specifier resolves to a versioned manifest.
+ * The standalone CLI keeps its own resolver (`standalone-cli.ts`), which runs
+ * outside Pi's loader.
+ */
+export function resolveInstalledPiAiVersion(
+	sources: PiAiVersionSources = defaultVersionSources,
+): string {
+	for (const specifier of ["@earendil-works/pi-ai/compat", "@earendil-works/pi-ai"]) {
+		const version = versionFrom(specifier, sources);
+		if (version !== undefined) return version;
+	}
+	return "pi-ai@unknown";
+}
+
+function versionFrom(specifier: string, sources: PiAiVersionSources): string | undefined {
+	try {
+		let directory = dirname(fileURLToPath(sources.resolve(specifier)));
+		for (let depth = 0; depth < 6; depth += 1) {
+			try {
+				const candidate = JSON.parse(
+					sources.readFile(join(directory, "package.json")),
+				) as { readonly name?: unknown; readonly version?: unknown };
+				if (
+					candidate.name === "@earendil-works/pi-ai" &&
+					typeof candidate.version === "string" &&
+					candidate.version.length > 0
+				) {
+					return `pi-ai@${candidate.version}`;
+				}
+			} catch {
+				// Keep walking toward the installed package root.
+			}
+			const parent = dirname(directory);
+			if (parent === directory) break;
+			directory = parent;
+		}
+	} catch {
+		// Resolution failure lets the caller try its next specifier.
+	}
+	return undefined;
+}

package/src/provider-registration.ts

@@ -573,6 +573,35 @@ function hasStreamResult(
 	return "result" in value && typeof value.result === "function";
 }
 
+const NO_ACTIVE_LOGICAL_SESSION_MESSAGE =
+	"No active unified logical provider session is available.";
+
+/** Terminal error stream for a call no live session can serve. */
+function noActiveLogicalSessionStream(modelId: string): AssistantMessageEventStream {
+	const stream = createAssistantMessageEventStream();
+	const error: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: LOGICAL_PROVIDER_ID,
+		provider: LOGICAL_PROVIDER_ID,
+		model: modelId,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "error",
+		errorMessage: NO_ACTIVE_LOGICAL_SESSION_MESSAGE,
+		timestamp: Date.now(),
+	};
+	stream.push({ type: "error", reason: "error", error });
+	stream.end(error);
+	return stream;
+}
+
 function deferredLogicalProviderStream(
 	upstream: Promise<AsyncIterable<unknown>>,
 ): AssistantMessageEventStream {
@@ -650,15 +679,90 @@ export const LOGICAL_API_SOURCE_ID = "hyphagroup-pi-multi-account-unified";
  */
 export type LogicalApiRegistrar = (
 	logicalStream: NonNullable<ProviderConfig["streamSimple"]>,
+	sessionId?: string,
 ) => () => void;
 
 type LogicalStream = NonNullable<ProviderConfig["streamSimple"]>;
 
 interface LogicalApiStreamOwner {
 	readonly owner: symbol;
+	/** The registering session's id, when known; the key a caller routes by. */
+	readonly sessionId: string | undefined;
 	readonly stream: LogicalStream;
 }
 
+/**
+ * Every live session's own logical stream, process-wide.
+ *
+ * In-process delegate workers and forks share the foreground session's
+ * `ModelRuntime`, so a worker's `registerProvider("unified")` replaces the
+ * foreground's `streamSimple` in that shared map, and Pi never restores it when
+ * the worker ends. Every registered stream is therefore a router: it serves the
+ * session whose id the caller passed (`options.sessionId`, which Pi sets on every
+ * agent-loop request), and never a released session. Without this, a foreground
+ * turn after a worker ended ran through the worker's invalidated extension
+ * context and failed with Pi's stale-ctx error until restart.
+ *
+ * Held on `globalThis` because Pi loads each session's extension with
+ * `moduleCache: false`, so module-level state is not shared between sessions.
+ */
+const LIVE_LOGICAL_SESSIONS_KEY = Symbol.for(
+	"hyphagroup.pi-multi-account.unified-live-sessions",
+);
+
+function liveLogicalSessions(): LogicalApiStreamOwner[] {
+	const holder = globalThis as unknown as Record<
+		symbol,
+		LogicalApiStreamOwner[] | undefined
+	>;
+	let sessions = holder[LIVE_LOGICAL_SESSIONS_KEY];
+	if (sessions === undefined) {
+		sessions = [];
+		holder[LIVE_LOGICAL_SESSIONS_KEY] = sessions;
+	}
+	return sessions;
+}
+
+/** Test-only: forget every live session so suites cannot leak routing state. */
+export function resetLogicalSessionRoutingForTests(): void {
+	liveLogicalSessions().length = 0;
+}
+
+function callerSessionId(options: unknown): string | undefined {
+	if (typeof options !== "object" || options === null) return undefined;
+	const sessionId = (options as { sessionId?: unknown }).sessionId;
+	return typeof sessionId === "string" && sessionId.length > 0
+		? sessionId
+		: undefined;
+}
+
+/**
+ * Pick the live stream that should serve one call: the caller's own session when
+ * its id is known and live, else the preferred owner if still live, else the
+ * newest live session. Ids Pi generates per call (compaction summaries receive a
+ * fresh routing id) match no session and take the fallback.
+ */
+function selectLogicalSessionStream(
+	candidates: readonly LogicalApiStreamOwner[],
+	options: unknown,
+	preferredOwner?: symbol,
+): LogicalApiStreamOwner | undefined {
+	const sessionId = callerSessionId(options);
+	if (sessionId !== undefined) {
+		for (let index = candidates.length - 1; index >= 0; index -= 1) {
+			const candidate = candidates[index];
+			if (candidate?.sessionId === sessionId) return candidate;
+		}
+	}
+	if (preferredOwner !== undefined) {
+		const preferred = candidates.find(
+			(candidate) => candidate.owner === preferredOwner,
+		);
+		if (preferred !== undefined) return preferred;
+	}
+	return candidates.at(-1);
+}
+
 interface LogicalApiRegistryGeneration {
 	readonly provider: NonNullable<ReturnType<typeof getApiProvider>>;
 	readonly streams: LogicalApiStreamOwner[];
@@ -678,7 +782,10 @@ let currentLogicalApiGeneration: LogicalApiRegistryGeneration | undefined;
 function createLogicalApiRegistryGeneration(): LogicalApiRegistryGeneration {
 	const streams: LogicalApiStreamOwner[] = [];
 	const currentStream: LogicalStream = (model, context, options) => {
-		const active = streams.at(-1);
+		// Select from the process-global list, not this module instance's
+		// `streams`: each session loads its own module copy, so a sibling's
+		// generation would otherwise know only its own sessions.
+		const active = selectLogicalSessionStream(liveLogicalSessions(), options);
 		if (active === undefined) {
 			throw new Error("No active unified logical provider session is available.");
 		}
@@ -732,7 +839,7 @@ function acquireLogicalApiRegistryGeneration(): LogicalApiRegistryGeneration {
  */
 export function createLogicalApiRegistrarForFactoryGeneration(): LogicalApiRegistrar {
 	let factoryGeneration: LogicalApiRegistryGeneration | undefined;
-	return (logicalStream) => {
+	return (logicalStream, sessionId) => {
 		const registered = getApiProvider(LOGICAL_PROVIDER_ID);
 		const generation =
 			factoryGeneration !== undefined && registered === factoryGeneration.provider
@@ -741,7 +848,7 @@ export function createLogicalApiRegistrarForFactoryGeneration(): LogicalApiRegis
 		factoryGeneration = generation;
 
 		const owner = Symbol("logical-session-stream");
-		generation.streams.push({ owner, stream: logicalStream });
+		generation.streams.push({ owner, sessionId, stream: logicalStream });
 		let released = false;
 		return () => {
 			if (released) return;
@@ -760,6 +867,7 @@ function registerProjectedLogicalProvider(
 	models: ModelDeclarationRow[],
 	deps: LogicalProviderDeps,
 	registerLogicalApi: LogicalApiRegistrar,
+	sessionId?: string,
 ): () => void {
 	const provider = createLogicalProvider(deps);
 	const streamSimple: NonNullable<ProviderConfig["streamSimple"]> = (
@@ -770,12 +878,34 @@ function registerProjectedLogicalProvider(
 		deferredLogicalProviderStream(
 			Promise.resolve(provider.streamSimple(model, context, options)),
 		);
+	const ownEntry: LogicalApiStreamOwner = {
+		owner: Symbol("logical-session"),
+		sessionId,
+		stream: streamSimple,
+	};
+	// The host-map stream routes by caller rather than closing over this session:
+	// a sibling in-process session may later own this slot of the shared runtime.
+	const routedStreamSimple: NonNullable<ProviderConfig["streamSimple"]> = (
+		model,
+		context,
+		options,
+	) => {
+		const selected = selectLogicalSessionStream(
+			liveLogicalSessions(),
+			options,
+			ownEntry.owner,
+		);
+		// Never fall back to a released session: its dependencies may hold an
+		// invalidated extension context.
+		if (selected === undefined) return noActiveLogicalSessionStream(model.id);
+		return selected.stream(model, context, options);
+	};
 	const providerConfig: ProviderConfig = {
 		name: LOGICAL_PROVIDER_DISPLAY_NAME,
 		api: LOGICAL_PROVIDER_ID,
 		baseUrl: DECLARATION_BASE_URL,
 		models,
-		streamSimple,
+		streamSimple: routedStreamSimple,
 	};
 	// Activate the compat stream BEFORE publishing the host provider, and bind it
 	// to the exact same logical stream the host provider uses. A throwing registrar
@@ -784,16 +914,32 @@ function registerProjectedLogicalProvider(
 	// selection, failover, attribution, or request options. The registrar is
 	// deliberately NOT wrapped here: swallowing its failure would publish a host
 	// provider whose `unified` API cannot resolve.
-	const releaseLogicalStream = registerLogicalApi(streamSimple);
+	const releaseLogicalStream = registerLogicalApi(streamSimple, sessionId);
+	const live = liveLogicalSessions();
+	// A reload re-registers the same session id; its previous registration is dead.
+	if (sessionId !== undefined) {
+		for (let index = live.length - 1; index >= 0; index -= 1) {
+			if (live[index]?.sessionId === sessionId) live.splice(index, 1);
+		}
+	}
+	live.push(ownEntry);
+	let released = false;
+	const release = (): void => {
+		if (released) return;
+		released = true;
+		const index = live.indexOf(ownEntry);
+		if (index !== -1) live.splice(index, 1);
+		releaseLogicalStream();
+	};
 	try {
 		pi.registerProvider(LOGICAL_PROVIDER_ID, providerConfig);
 	} catch (error) {
 		// Remove only this failed session's stream. The process-global API entry is
 		// generation-owned and remains available to any preceding live session.
-		releaseLogicalStream();
+		release();
 		throw error;
 	}
-	return releaseLogicalStream;
+	return release;
 }
 
 function safeAttributionCall(call: () => void): void {
@@ -860,6 +1006,7 @@ export function registerLogicalProviderForSession(
 	projectedModels: unknown[],
 	deps: LogicalProviderDeps,
 	registerLogicalApi: LogicalApiRegistrar = registerLogicalApiWithCompat,
+	options: { readonly sessionId?: string } = {},
 ): LogicalProviderSessionRegistration {
 	const models = assertProjectedManagedModels(projectedModels);
 	const rawLifecycle: LogicalAttributionLifecycle = deps.attribution ?? {
@@ -882,6 +1029,7 @@ export function registerLogicalProviderForSession(
 			models,
 			sessionDeps,
 			registerLogicalApi,
+			options.sessionId,
 		);
 	} catch (error) {
 		// registerProjectedLogicalProvider already removed any activated session

package/src/routing.ts

@@ -98,7 +98,18 @@ export interface PausedRoute {
 	readonly retryAfterMs: number | null;
 }
 
-export type ReactiveRouteDecision = SelectedRoute | PausedRoute;
+/**
+ * A structured refusal or unknown provider stop. The failed account is kept
+ * as-is: no cooldown, no invalidation, no alternative, and no continuation.
+ * The stop is deterministic for the request context, so another account would
+ * only spend another request on the same answer.
+ */
+export interface RetainedRoute {
+	readonly status: "retained";
+	readonly classification: FailureClassification;
+}
+
+export type ReactiveRouteDecision = SelectedRoute | PausedRoute | RetainedRoute;
 
 export interface HealthSelectionDecision {
 	readonly providerId: string;
@@ -1092,6 +1103,11 @@ export function routeAfterFailure(options: {
 		throw new TypeError("failedAccount must be a canonical managed provider.");
 	}
 	const classification = classifyFailure(failure);
+	// Before any state observation: a retained stop writes nothing and routes
+	// nowhere, so settlement cannot turn it into a switch or a continuation.
+	if (classification.accountAction === "retain-account") {
+		return { status: "retained", classification };
+	}
 	if (
 		classification.category === "config" &&
 		failure.code === "model_not_found" &&