@centerforagenticai/pi-multi-account 0.1.2 → 0.1.5

package/src/host-final-stop-message.ts

@@ -0,0 +1,136 @@
+import {
+	isContextOverflow,
+	isRetryableAssistantError,
+	type AssistantMessage,
+} from "@earendil-works/pi-ai";
+import { sanitizeDiagnosticText } from "./diagnostics.js";
+
+/** Fixed fallbacks for a structured provider stop; none matches a host re-dispatch pattern. */
+export const REFUSAL_FALLBACK_MESSAGE = "The model refused to complete the request";
+export const UNKNOWN_STOP_FALLBACK_MESSAGE =
+	"Provider stopped with an unrecognized stop reason";
+
+/**
+ * Appended when a reworded unknown stop reason omits words a host predicate acts
+ * on, so the published reason does not read as complete. Neither pinned
+ * predicate matches it, and the marked message is probed again before use.
+ */
+export const PARTLY_WITHHELD_MARKER = " (partly withheld)";
+
+/** Upper bound on the normalized stop reason named in a reworded message. */
+const MAX_NAMED_REASON_LENGTH = 64;
+
+/**
+ * Whether the pinned host would re-dispatch an error terminal carrying `text`.
+ *
+ * The host re-dispatches when either retry predicate matches the prose:
+ * `AgentSession._isRetryableError` runs pi-ai `isRetryableAssistantError`, and
+ * `_checkCompaction` runs `isContextOverflow` before compacting and retrying once
+ * (pi-coding-agent dist/core/agent-session.js, both from `@earendil-works/pi-ai`).
+ * An unreadable predicate result counts as a match, so the caller keeps looking
+ * for a safer form.
+ */
+export function hostWouldRedispatch(message: AssistantMessage, text: string): boolean {
+	try {
+		const probe = { ...message, errorMessage: text };
+		return isRetryableAssistantError(probe) || isContextOverflow(probe, 0);
+	} catch {
+		return true;
+	}
+}
+
+function namedReasonMessage(reason: string): string {
+	return `Provider stopped (reason: ${reason})`;
+}
+
+/**
+ * Normalizes a bounded, sanitized raw stop reason into plain words: every run of
+ * non-alphanumeric characters (underscores included) becomes one space, and the
+ * result is capped at a word boundary where possible.
+ */
+function normalizedReasonWords(rawStopReason: unknown): string[] {
+	if (typeof rawStopReason !== "string") return [];
+	const words = sanitizeDiagnosticText(rawStopReason)
+		.replace(/[^A-Za-z0-9]+/g, " ")
+		.trim()
+		.split(" ")
+		.filter((word) => word.length > 0);
+	const kept: string[] = [];
+	let length = 0;
+	for (const word of words) {
+		const next = length === 0 ? word.length : length + 1 + word.length;
+		if (next > MAX_NAMED_REASON_LENGTH) {
+			if (kept.length === 0) kept.push(word.slice(0, MAX_NAMED_REASON_LENGTH));
+			break;
+		}
+		kept.push(word);
+		length = next;
+	}
+	return kept;
+}
+
+/**
+ * Names an unknown stop reason in a message neither host predicate acts on.
+ *
+ * The first form keeps every normalized word. When that still matches a host
+ * predicate (a reason containing "overloaded" or "timeout", say), the second
+ * form admits words in order and drops each one whose addition would make the
+ * message match. When any word was dropped the result ends with
+ * `PARTLY_WITHHELD_MARKER`; that marked text is probed too, and an unsafe or
+ * empty result yields `undefined`.
+ */
+function unknownStopNamingReason(
+	message: AssistantMessage,
+	rawStopReason: unknown,
+): string | undefined {
+	const words = normalizedReasonWords(rawStopReason);
+	if (words.length === 0) return undefined;
+	const reworded = namedReasonMessage(words.join(" "));
+	if (!hostWouldRedispatch(message, reworded)) return reworded;
+	const kept: string[] = [];
+	for (const word of words) {
+		const tentative = namedReasonMessage([...kept, word].join(" "));
+		if (!hostWouldRedispatch(message, tentative)) kept.push(word);
+	}
+	if (kept.length === 0) return undefined;
+	const named = namedReasonMessage(kept.join(" "));
+	if (kept.length === words.length) return named;
+	const marked = `${named}${PARTLY_WITHHELD_MARKER}`;
+	return hostWouldRedispatch(message, marked) ? undefined : marked;
+}
+
+/**
+ * The public error text for a structured refusal or unknown provider stop.
+ *
+ * The pinned host re-dispatches an error terminal from its prose alone (see
+ * `hostWouldRedispatch`). A refusal explanation or stop reason is
+ * provider-authored, so text such as "overloaded", "prompt is too long", or
+ * "model_context_window_exceeded" would make the host send the stopped request
+ * again. The structured code alone selects this path; the provider text is kept
+ * only when neither host predicate would act on it. An unknown stop is then
+ * reworded so it still names its reason, and only when no reworded form is safe
+ * is a fixed fallback published. A refusal whose explanation is unsafe publishes
+ * its fixed fallback directly. A message without the structured code, or that is
+ * not an error terminal, yields `undefined` and must be published unchanged.
+ */
+export function hostFinalStopMessage(
+	message: AssistantMessage,
+): { readonly errorMessage: string } | undefined {
+	const code = (message as { code?: unknown }).code;
+	if (message.stopReason !== "error") return undefined;
+	if (code !== "refusal" && code !== "unknown_stop") return undefined;
+	const candidate = message.errorMessage;
+	if (
+		typeof candidate === "string" &&
+		candidate.length > 0 &&
+		!hostWouldRedispatch(message, candidate)
+	) {
+		return { errorMessage: candidate };
+	}
+	if (code === "refusal") return { errorMessage: REFUSAL_FALLBACK_MESSAGE };
+	return {
+		errorMessage:
+			unknownStopNamingReason(message, message.rawStopReason) ??
+			UNKNOWN_STOP_FALLBACK_MESSAGE,
+	};
+}

package/src/index.ts

@@ -80,6 +80,7 @@ import {
 import { DiagnosticStore } from "./diagnostic-store.js";
 import { DeclarationNoticeMarker } from "./declaration-notice-marker.js";
 import { DiagnosticLog } from "./diagnostics.js";
+import { createRefusalAdvisor } from "./refusal-advice.js";
 import {
 	classifyProviderId,
 	createPublicAuthStorageAdapter,
@@ -3890,6 +3891,18 @@ export const createMultiAccountExtension =
 				modelSupport,
 				alreadyCooled: classified.alreadyCooled === true,
 			});
+			if (decision.status === "retained") {
+				// A structured refusal or unknown stop keeps the account: no switch,
+				// no park, no OpenRouter, and no continuation. The same context would
+				// stop the same way on any account.
+				diagnostics.record(
+					"info",
+					"routing.retained",
+					"The provider stopped the turn with a refusal or unknown stop reason; the account was kept and no follow-up was scheduled.",
+					{ providerId, kind: decision.classification.kind ?? "unknown" },
+				);
+				return;
+			}
 			if (decision.status === "paused") {
 				// OpenRouter is an explicitly enabled, metered FINAL rung. The helper
 				// re-checks every managed family so family-chain policy cannot bypass
@@ -4147,6 +4160,9 @@ export const createMultiAccountExtension =
 		const lastFailure = new Map<string, ProviderFailureSignal>();
 		const handledFailures = new WeakSet<object>();
 		const observedMessages = new WeakSet<object>();
+		// Operator advice for a structured refusal. A delegate-owned in-process
+		// session shares the foreground UI, so only the foreground advises.
+		const refusalAdvisor = createRefusalAdvisor({ foreground: !delegateOwnedSession });
 		const recordUsage = (
 			observation: () => UsageObservation | undefined,
 		): void => {
@@ -4873,7 +4889,7 @@ export const createMultiAccountExtension =
 								config,
 								nowMs,
 							});
-							if (reactive.status === "paused") return;
+							if (reactive.status !== "selected") return;
 							reactiveCandidate = reactive;
 							destinationProviderId = reactive.destination.providerId;
 						}
@@ -5141,6 +5157,17 @@ export const createMultiAccountExtension =
 						acceptedLogicalAssociation,
 					);
 				}
+				// Advice only: names the physical route that refused, never routes.
+				refusalAdvisor.advise(
+					originalMessage,
+					messageContext,
+					acceptedLogicalAssociation && logicalAssociation !== undefined
+						? {
+								providerId: logicalAssociation.route.providerId,
+								modelId: logicalAssociation.dispatchedModelId,
+							}
+						: {},
+				);
 
 				try {
 					const validOriginalMessage = originalMessage as AssistantMessage;
@@ -5228,6 +5255,8 @@ export const createMultiAccountExtension =
 			) {
 				return;
 			}
+			// Advice only: a managed account's structured refusal never routes.
+			refusalAdvisor.advise(event.message, messageContext, identity);
 			const subscriptionFamily = isRoutingEligibleAccountFamily(messageSlot)
 				? messageSlot.family
 				: undefined;
@@ -5299,9 +5328,17 @@ export const createMultiAccountExtension =
 			turnRouteOrigin = origin;
 			handledFailures.add(event.message);
 			const responseFailure = lastFailure.get(providerId) ?? {};
-			const messageCode = providerErrorCodeFromMessage(
-				event.message.errorMessage,
-			);
+			// A structured provider stop is copied only from this two-value allowlist,
+			// never spread, and it wins over any code parsed from provider-authored
+			// errorMessage prose: refusal text must not read as a rate limit.
+			const rawStopCode = (event.message as { code?: unknown }).code;
+			const stopCode =
+				rawStopCode === "refusal" || rawStopCode === "unknown_stop"
+					? rawStopCode
+					: undefined;
+			const messageCode =
+				stopCode ??
+				providerErrorCodeFromMessage(event.message.errorMessage);
 			const failure: ProviderFailureSignal = {
 				...responseFailure,
 				...(messageCode === undefined ? {} : { code: messageCode }),

package/src/logical-provider.ts

@@ -16,12 +16,14 @@
 import { logicalAccountEligible, recordFailureCooldown } from "./routing.js";
 import type { ManagedAccount } from "./routing.js";
 import {
+	isContextOverflow,
 	isRetryableAssistantError,
 	type AssistantMessage,
 	type ProviderResponse,
 	type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
 import { RuntimeState, type LogicalRoutePin } from "./runtime-state.js";
+import { hostFinalStopMessage } from "./host-final-stop-message.js";
 import { DEFAULT_CONFIG } from "./config.js";
 import type {
 	AllowedFamily,
@@ -47,6 +49,16 @@ import type { ProviderType, Vendor } from "./vendor.js";
 
 export { LOGICAL_PROVIDER_ID } from "./models-declaration.js";
 import { LOGICAL_PROVIDER_ID } from "./models-declaration.js";
+import { forceCodexSseOptions } from "./codex-adapter.js";
+
+/** Fixed diagnostic label for a caller-supplied transport; never echoes the raw value. */
+function codexTransportLabel(
+	transport: unknown,
+): "websocket" | "websocket-cached" | "auto" | "other" {
+	return transport === "websocket" || transport === "websocket-cached" || transport === "auto"
+		? transport
+		: "other";
+}
 
 /** One physical account the logical provider may dispatch to. */
 export interface LogicalPhysicalAccount {
@@ -342,6 +354,36 @@ const EXHAUSTION_LENGTH_ALLOWANCE_MULTIPLIER = 8;
 const EXHAUSTION_LENGTH_MAX_CONTEXT_FRACTION = 0.8;
 const EXHAUSTION_LENGTH_ERROR_MESSAGE = "provider returned error (usage-limit)";
 
+/**
+ * Fixed public text for a setup-shaped context overflow. The pinned host's
+ * `isContextOverflow` matches it (so the host compacts and retries once) and
+ * `isRetryableAssistantError` does not (so the host does not fail over).
+ */
+export const SETUP_CONTEXT_OVERFLOW_MESSAGE = "context_length_exceeded (provider_error)";
+
+type SetupFailureDisposition = "context-overflow" | "retryable" | "host-final";
+
+/**
+ * How the pinned host treats the raw setup text. The host checks the two
+ * predicates separately: `_handlePostAgentRun` compacts and retries once on
+ * `isContextOverflow`, while `_isRetryableError` excludes overflow and fails
+ * over on `isRetryableAssistantError`. An unreadable predicate result counts
+ * as host-final.
+ */
+function setupFailureDisposition(
+	message: AssistantMessage,
+	raw: unknown,
+): SetupFailureDisposition {
+	if (typeof raw !== "string" || raw.length === 0) return "host-final";
+	try {
+		const probe = { ...message, errorMessage: raw };
+		if (isContextOverflow(probe, 0)) return "context-overflow";
+		return isRetryableAssistantError(probe) ? "retryable" : "host-final";
+	} catch {
+		return "host-final";
+	}
+}
+
 function finiteNonNegative(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0
 		? value
@@ -531,6 +573,54 @@ function projectFailureSignal(
 	};
 }
 
+/**
+ * Whether a physical terminal is the host's setup-error shape: the first event
+ * of the stream is an `error` with no content, all-zero usage, no diagnostics,
+ * no structured stop code, and no structured failure evidence.
+ *
+ * That is what pi-ai `lazyStream` (`createSetupErrorMessage`) publishes when a
+ * provider stream throws or rejects before it starts, so its `errorMessage` is
+ * raw exception text, not provider-authored failure prose. The production cause
+ * of the observed setup `TypeError` is not known (see UPSTREAM.md). The same
+ * shape also carries transient pre-start failures ("fetch failed", a 503 before
+ * `start`), so the caller decides retryability from the text, never publishes
+ * it. A real provider failure that carries a recognized code or status keeps
+ * its own text and routing.
+ */
+function isUnclassifiedSetupFailure(
+	message: AssistantMessage,
+	failure: ProviderFailureSignal,
+): boolean {
+	try {
+		if (message.stopReason !== "error") return false;
+		if (!Array.isArray(message.content) || message.content.length !== 0) return false;
+		const diagnostics = (message as { diagnostics?: unknown }).diagnostics;
+		if (diagnostics !== undefined && !(Array.isArray(diagnostics) && diagnostics.length === 0)) {
+			return false;
+		}
+		if ((message as { code?: unknown }).code !== undefined) return false;
+		const usage = projectTerminalUsage(message);
+		if (
+			usage === undefined ||
+			usage.input !== 0 ||
+			usage.output !== 0 ||
+			usage.cacheRead !== 0 ||
+			usage.cacheWrite !== 0 ||
+			usage.totalTokens !== 0 ||
+			usage.cost.total !== 0
+		) {
+			return false;
+		}
+		return (
+			failure.code === undefined &&
+			failure.httpStatus === undefined &&
+			failure.transportKind === undefined
+		);
+	} catch {
+		return false;
+	}
+}
+
 function safeProjectFailureSignal(
 	error: unknown,
 	modelId: string,
@@ -666,6 +756,7 @@ export function createLogicalProvider(
 	deps: LogicalProviderDeps,
 ): LogicalProvider {
 	const coordinator = createHostRetryCoordinator(deps);
+	let codexTransportNoticeSent = false;
 
 	const diagnose = (message: string): void => {
 		deps.onDiagnostic?.(message);
@@ -936,6 +1027,7 @@ export function createLogicalProvider(
 
 	const projectMessage = (message: AssistantMessage, modelId: string): AssistantMessage => ({
 		...message, api: LOGICAL_PROVIDER_ID, provider: LOGICAL_PROVIDER_ID, model: modelId,
+		...hostFinalStopMessage(message),
 	});
 
 	const projectEvent = (event: unknown, modelId: string): unknown => {
@@ -951,6 +1043,18 @@ export function createLogicalProvider(
 		return { ...candidate, [key]: projectMessage(value as AssistantMessage, modelId) };
 	};
 
+	const withPublicErrorMessage = (event: unknown, errorMessage: string): unknown => {
+		if (typeof event !== "object" || event === null) return event;
+		const candidate = event as Record<string, unknown>;
+		if (candidate.type !== "error" || typeof candidate.error !== "object" || candidate.error === null) {
+			return event;
+		}
+		return {
+			...candidate,
+			error: { ...(candidate.error as AssistantMessage), errorMessage },
+		};
+	};
+
 	const watchStream = (
 		stream: AsyncIterable<unknown>,
 		model: unknown,
@@ -962,6 +1066,7 @@ export function createLogicalProvider(
 	): AsyncIterable<unknown> => ({
 		async *[Symbol.asyncIterator]() {
 			let sawTerminal = false;
+			let sawEvent = false;
 			let failureReceipt: HostRetryCooldownReceipt | undefined;
 			const recordFailureOnce = (error: unknown): HostRetryCooldownReceipt => {
 				failureReceipt ??= coordinator.recordFailure({
@@ -1003,7 +1108,10 @@ export function createLogicalProvider(
 							? (event as { type?: unknown }).type
 							: undefined;
 					if (eventType === "done" || eventType === "error") sawTerminal = true;
+					const firstEvent = !sawEvent;
+					sawEvent = true;
 					const terminal = terminalAttribution(event);
+					let setupFailureMessage: string | undefined;
 					if (terminal !== undefined) {
 						const { message, outcome } = terminal;
 						if (outcome === "finish") {
@@ -1035,10 +1143,41 @@ export function createLogicalProvider(
 						} else {
 							const failure = safeProjectFailureSignal(message, dispatchedModelId);
 							attributeFailure(message, failure, recordFailureOnce(message));
+							if (firstEvent && isUnclassifiedSetupFailure(message, failure)) {
+								// The physical account is cooled above exactly like any other
+								// failure. Only the published text changes: the raw text is
+								// replaced by the bounded classified message the
+								// rejected-dispatch path uses, so it is never published. The
+								// setup shape is shared by transient pre-start failures ("fetch
+								// failed", a 503 before `start`), pre-start context overflows
+								// (a Codex 400 or Anthropic 413), and deterministic setup throws.
+								// The raw text decides the form: an overflow publishes a fixed
+								// overflow message so the host compacts instead of failing
+								// over; a host-retryable text keeps the retryable form and
+								// fails over; anything else is host-final (`provider_error`),
+								// so a deterministic fault is not repeated on the next account.
+								const disposition = setupFailureDisposition(message, message.errorMessage);
+								setupFailureMessage =
+									disposition === "context-overflow"
+										? SETUP_CONTEXT_OVERFLOW_MESSAGE
+										: classifiedErrorMessage(failure, disposition === "retryable");
+								try {
+									deps.onDiagnostic?.(
+										`logical dispatch for ${account.providerId} failed during stream setup; ` +
+											"published a classified failure instead of the raw setup error",
+									);
+								} catch {
+									// A diagnostic sink failure cannot replace a provider result.
+								}
+							}
 						}
 						await attempt.waitForTerminal();
 					}
-					const publicEvent = projectEvent(event, requestedModelId);
+					const projectedEvent = projectEvent(event, requestedModelId);
+					const publicEvent =
+						setupFailureMessage === undefined
+							? projectedEvent
+							: withPublicErrorMessage(projectedEvent, setupFailureMessage);
 					if (terminal !== undefined && publicEvent !== event) {
 						const publicTerminal = terminalAttribution(publicEvent);
 						if (publicTerminal !== undefined) {
@@ -1127,8 +1266,24 @@ export function createLogicalProvider(
 					await originalOnResponse(response, responseModel);
 				}
 			};
+			let routedOptions = options;
+			if (account.family === "openai-codex") {
+				// Temporary Pi 0.99 WebSocket containment; see CODEX_FORCED_TRANSPORT.
+				const forced = forceCodexSseOptions(options);
+				routedOptions = forced.options;
+				if (forced.overridden && options?.transport !== undefined && !codexTransportNoticeSent) {
+					codexTransportNoticeSent = true;
+					try {
+						deps.onDiagnostic?.(
+							`Codex transport "${codexTransportLabel(options.transport)}" overridden to "sse" on routed calls (Pi 0.99 WebSocket containment).`,
+						);
+					} catch {
+						// A diagnostic sink failure cannot replace a provider result.
+					}
+				}
+			}
 			const attributedOptions: SimpleStreamOptions = {
-				...options,
+				...routedOptions,
 				onPayload: wrappedOnPayload,
 				onResponse: wrappedOnResponse,
 			};