@centerforagenticai/pi-multi-account 0.1.4 → 0.1.5

package/src/recovery-plan.ts

@@ -30,6 +30,9 @@ export type RecoveryCandidateTier =
 	| "owning-vendor-api"
 	| "cross-family-subscription";
 
+/** The one recovery dimension a candidate may change for this logical call. */
+export type RecoveryActionKind = "account" | "model";
+
 /** One finite provider/model pair. Logical and physical model identity stay distinct. */
 export interface RecoveryCandidate {
 	readonly providerId: string;
@@ -39,6 +42,7 @@ export interface RecoveryCandidate {
 	readonly selectedModelId: string;
 	readonly tier: RecoveryCandidateTier;
 	readonly substitution: "exact" | "configured";
+	readonly recoveryAction: RecoveryActionKind;
 	readonly capability: RecoveryModelCapability;
 }
 
@@ -91,7 +95,7 @@ function immutableCapability(model: RecoveryModelCapability): RecoveryModelCapab
 	});
 }
 
-/** Build the immutable, deterministic candidate sweep for one logical call. */
+/** Build the immutable, deterministic candidate order for one logical call. */
 export function buildRecoveryCandidatePlan(
 	request: RecoveryCandidatePlanRequest,
 ): readonly RecoveryCandidate[] {
@@ -146,6 +150,8 @@ export function buildRecoveryCandidatePlan(
 				selectedModelId: request.selectedModelId,
 				tier,
 				substitution,
+				recoveryAction:
+					model.modelId === request.selectedModelId ? "account" : "model",
 				capability: immutableCapability(model),
 			}),
 		);

package/src/recovery-send-evidence.ts

@@ -0,0 +1,29 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+
+export type CodexRecoverySendEvidence = "pre-execution-rejected" | "uncertain";
+
+/**
+ * Classify whether a pinned Codex WebSocket terminal proves that one request was
+ * rejected before execution without an internal reconnect or SSE fallback.
+ *
+ * Pinned pi-ai 0.84.4 sends `response.create` before it observes stream events
+ * (`dist/api/openai-codex-responses.js:1182`). Its WebSocket loop can reconnect
+ * for two special errors or fall back to SSE (`:218-245`). The
+ * `provider_transport_failure` diagnostic is appended only on that transport
+ * branch (`:229-237`). Structured `CodexApiError` fields are instead normalized
+ * to terminal `errorMessage` (`:483-539`, `:344-346`), which retains neither the
+ * code/payload nor proof that no prior reconnect occurred.
+ *
+ * The per-session `getOpenAICodexWebSocketDebugStats` counters (`:632-654`)
+ * are process-global, shared by concurrent requests, and absent from the
+ * terminal, so they cannot attribute sends to one invocation either.
+ *
+ * Consequently no terminal `AssistantMessage` exposed by the pinned package is
+ * trustworthy proof of the complete condition. Do not infer safety from prose,
+ * status-like text, or the absence of a transport diagnostic.
+ */
+export function classifyCodexRecoverySendEvidence(
+	_terminal: AssistantMessage,
+): CodexRecoverySendEvidence {
+	return "uncertain";
+}

package/src/refusal-advice.ts

@@ -0,0 +1,139 @@
+/**
+ * Operator-only advice for a structured provider refusal.
+ *
+ * A refusal is an outcome, not an account failure: routing keeps the account
+ * and nothing is resent (see `src/routing.ts`, status `retained`). This module
+ * only tells the operator what happened and which choices remain. It never
+ * resends, rephrases, starts a turn, changes the model, rotates an account, or
+ * writes state.
+ *
+ * Only the structured `code` field selects advice. The adapter sets it from the
+ * provider's own stop reason (`src/anthropic-adaptive-stream.ts`). Assistant
+ * prose, the error message, the raw stop reason, and content are never read,
+ * so a refusal is never guessed and no provider text can reach the advice.
+ */
+
+/** Identical advice inside this window is shown once. */
+export const REFUSAL_ADVICE_REPEAT_WINDOW_MS = 60_000;
+
+/** Provider and model IDs are named only when they are short, plain tokens. */
+const SAFE_ROUTE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
+
+const CHOICES =
+	"Multi-account kept the account and did not resend, reroute, or retry it. " +
+	"You can revise the request, or pick another model explicitly with /model.";
+
+export type RefusalAdviceRoute = Readonly<{
+	providerId?: unknown;
+	modelId?: unknown;
+}>;
+
+/** Reads one own data property; accessors and proxies count as absent. */
+function ownDataValue(value: object, key: string): unknown {
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	return descriptor !== undefined && "value" in descriptor
+		? descriptor.value
+		: undefined;
+}
+
+/**
+ * The allowlisted projection: whether `message` is an assistant error terminal
+ * carrying the exact structured `refusal` code. Nothing else is read.
+ */
+export function isStructuredRefusal(message: unknown): boolean {
+	try {
+		if (typeof message !== "object" || message === null) return false;
+		return (
+			ownDataValue(message, "role") === "assistant" &&
+			ownDataValue(message, "stopReason") === "error" &&
+			ownDataValue(message, "code") === "refusal"
+		);
+	} catch {
+		return false;
+	}
+}
+
+function safeRouteId(value: unknown): string | undefined {
+	return typeof value === "string" && SAFE_ROUTE_ID.test(value)
+		? value
+		: undefined;
+}
+
+function safeRouteLabel(route: RefusalAdviceRoute): string | undefined {
+	try {
+		const providerId = safeRouteId(route.providerId);
+		const modelId = safeRouteId(route.modelId);
+		return providerId === undefined || modelId === undefined
+			? undefined
+			: `${providerId}/${modelId}`;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Bounded advice text for a structured refusal, or `undefined` when the message
+ * carries no structured refusal code. The text names only the route identity
+ * the caller resolved, and drops it when it is not a short plain token.
+ */
+export function refusalAdvice(
+	message: unknown,
+	route: RefusalAdviceRoute,
+): string | undefined {
+	if (!isStructuredRefusal(message)) return undefined;
+	const label = safeRouteLabel(route);
+	const subject =
+		label === undefined ? "The model refused this request." : `${label} refused this request.`;
+	return `${subject} ${CHOICES}`;
+}
+
+type NotifyContext = {
+	readonly hasUI?: unknown;
+	readonly ui?: { notify?: unknown };
+};
+
+export type RefusalAdvisorOptions = Readonly<{
+	/** False for delegate-owned sessions that share the foreground UI. */
+	foreground: boolean;
+	now?: () => number;
+}>;
+
+/**
+ * Shows refusal advice in the foreground UI at most once per terminal and once
+ * per route inside {@link REFUSAL_ADVICE_REPEAT_WINDOW_MS}. Fail-soft: a UI
+ * failure never reaches the caller. Returns whether advice was shown.
+ */
+export function createRefusalAdvisor(options: RefusalAdvisorOptions) {
+	const now = options.now ?? Date.now;
+	const advised = new WeakSet<object>();
+	let lastText: string | undefined;
+	let lastAtMs = Number.NEGATIVE_INFINITY;
+	return {
+		advise(
+			message: unknown,
+			context: NotifyContext | undefined,
+			route: RefusalAdviceRoute,
+		): boolean {
+			try {
+				if (!options.foreground) return false;
+				const text = refusalAdvice(message, route);
+				if (text === undefined) return false;
+				if (advised.has(message as object)) return false;
+				advised.add(message as object);
+				if (context?.hasUI !== true) return false;
+				const notify = context.ui?.notify;
+				if (typeof notify !== "function") return false;
+				const atMs = now();
+				if (text === lastText && atMs - lastAtMs < REFUSAL_ADVICE_REPEAT_WINDOW_MS) {
+					return false;
+				}
+				lastText = text;
+				lastAtMs = atMs;
+				notify.call(context.ui, text, "warning");
+				return true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}

package/src/shared-usage.ts

@@ -905,10 +905,14 @@ export class SharedUsageStore {
 
 	append(record: SharedUsageLogRecord): boolean {
 		try {
-			// Judge the caller's own value, not the projection: projecting slices
-			// the observer id, and a value this store would have to rewrite is
-			// not one the producer emitted.
-			if (!validObserverId((record as { observerId?: unknown }).observerId))
+			// The store is the ONLY producer of a persisted observer id
+			// (internal issue #133). The grammar check alone cannot keep a
+			// credential out: `sk-ant-api03-...` is a valid hostname-shaped id, and
+			// no character rule separates a hostname from a key. So a caller may
+			// only restate this store's own id, which the constructor validated;
+			// any other value, a peer's included, is refused rather than written.
+			// Judged on the caller's own value, before projection slices it.
+			if ((record as { observerId?: unknown }).observerId !== this.#observerId)
 				return false;
 			const projected = validExhaustionHoldRecord(record)
 				? projectExhaustionHold(record)
@@ -1063,15 +1067,28 @@ export class SharedUsageStore {
 		return latest;
 	}
 
+	/**
+	 * The newest attempt for an account that was observed at or before `nowMs`.
+	 *
+	 * An attempt observed in the future is ignored here, at the single source,
+	 * rather than by each reader (internal issue #133). Such a record always
+	 * sorts as the newest, so a reader that merely declined to be suppressed by
+	 * it still took its `failureCount` as the prior rung: every real failure
+	 * rewrote the same count, the next read returned the future record again,
+	 * and the backoff ladder froze. `nowMs` is required so each reader judges
+	 * against its own (possibly injected) clock.
+	 */
 	latestAttempt(
 		providerId: string,
 		family: AllowedFamily,
+		nowMs: number,
 	): SharedUsageAttemptRecord | undefined {
 		let latest: SharedUsageAttemptRecord | undefined;
 		for (const record of this.readAttempts()) {
 			if (
 				record.providerId === providerId &&
 				record.family === family &&
+				record.observedAtMs <= nowMs &&
 				(latest === undefined || record.observedAtMs >= latest.observedAtMs)
 			) {
 				latest = record;

package/src/usage-fetch.ts

@@ -641,36 +641,27 @@ async function queryEndpoint(
 		: normalizeAnthropicUsagePayload(payload);
 }
 
-/**
- * The attempt's deadline, or undefined when no honest ladder could have set it.
- *
- * The store already bounds `nextAttemptAtMs` against the record's own
- * `observedAtMs` on append and read (internal issue #108). That span
- * check alone is not enough for a reader: a record whose ORIGIN sits centuries
- * ahead carries a legitimate-looking span and would still suppress polling for
- * that account forever. No honest deadline lies further than one capped rung
- * from now, so anything beyond that is ignored rather than trusted.
- */
-function plausibleAttemptDeadline(
-	attempt: SharedUsageAttemptRecord | undefined,
-	nowMs: number,
-): number | undefined {
-	if (attempt === undefined) return undefined;
-	if (attempt.nextAttemptAtMs > nowMs + MAX_USAGE_ATTEMPT_DELAY_MS) {
-		return undefined;
-	}
-	return attempt.nextAttemptAtMs;
-}
+// Every attempt a reader here sees comes from `SharedUsageStore.latestAttempt`
+// called with that reader's own clock, and that is what keeps a far-future
+// deadline (internal issue #108) from suppressing polling:
+//
+//  - the store refuses, on append and read, any attempt whose
+//    `nextAttemptAtMs - observedAtMs` exceeds MAX_USAGE_ATTEMPT_DELAY_MS; and
+//  - `latestAttempt` skips any attempt observed after `nowMs` (#133).
+//
+// Together these give `nextAttemptAtMs <= nowMs + MAX_USAGE_ATTEMPT_DELAY_MS`
+// for every record a reader receives. A per-reader "plausible deadline" check
+// used to restate that bound; once the origin filter moved into the store it
+// could no longer fail on any reachable input and was removed (#133,
+// CR-REFRESH-READER-BOUND-UNREACHABLE). Read attempts only through
+// `latestAttempt(providerId, family, nowMs)` with the clock the decision uses.
 
 function statusFromAttempt(
 	attempt: SharedUsageAttemptRecord | undefined,
 	enabled: boolean,
-	nowMs: number,
 ): UsageFetchStatus {
 	const nextAttemptAtMs =
-		attempt?.failureCount === 0
-			? undefined
-			: plausibleAttemptDeadline(attempt, nowMs);
+		attempt?.failureCount === 0 ? undefined : attempt?.nextAttemptAtMs;
 	const disabledReason = attempt?.failureReason;
 	return {
 		enabled,
@@ -853,9 +844,8 @@ export class UsageFetcher {
 	): UsageFetchStatus {
 		const enabled = config.usageFetchEnabled?.[family] ?? true;
 		return statusFromAttempt(
-			this.#sharedStore.latestAttempt(providerId, family),
+			this.#sharedStore.latestAttempt(providerId, family, this.#now()),
 			enabled,
-			this.#now(),
 		);
 	}
 
@@ -1017,25 +1007,20 @@ export class UsageFetcher {
 		// the debounce clause, so `already-answered` and `backoff` returned
 		// before it ran: an attempt with `observedAtMs` centuries ahead is
 		// trivially `>= failedAtMs`, and suppressed every failure refresh
-		// forever. The bound belongs here, on the record, before any clause
-		// reads it.
+		// forever. `latestAttempt(..., nowMs)` now refuses such a record at the
+		// source (#133), which also bounds `nextAttemptAtMs` to one capped rung
+		// past `nowMs` (see the note above `statusFromAttempt`).
 		//
-		// `nextAttemptAtMs` is bounded relative to `observedAtMs` by the store and
-		// checked again here before it may suppress a send. An honest record cannot
-		// have been OBSERVED in the future either.
+		// The failure trigger is not tied to `observedAtMs` by the store, so a
+		// record observed in the past can still name a failure in the future;
+		// such a marker cannot be honest and must not arm the debounce.
 		if (
-			attempt.observedAtMs > nowMs ||
-			(attempt.failureTriggeredAtMs !== undefined &&
-				attempt.failureTriggeredAtMs > nowMs)
+			attempt.failureTriggeredAtMs !== undefined &&
+			attempt.failureTriggeredAtMs > nowMs
 		) {
 			return undefined;
 		}
-		const nextAttemptAtMs = plausibleAttemptDeadline(attempt, nowMs);
-		if (
-			attempt.failureCount > 0 &&
-			nextAttemptAtMs !== undefined &&
-			nextAttemptAtMs > nowMs
-		) {
+		if (attempt.failureCount > 0 && attempt.nextAttemptAtMs > nowMs) {
 			return "backoff";
 		}
 		if (attempt.observedAtMs >= failedAtMs) return "already-answered";
@@ -1070,15 +1055,17 @@ export class UsageFetcher {
 		}
 
 		// Step 4/5: durable checks before the lease.
+		const beforeLeaseNowMs = this.#now();
 		const beforeLease = this.#sharedStore.latestAttempt(
 			account.providerId,
 			account.family,
+			beforeLeaseNowMs,
 		);
 		if (
 			this.#failureRefreshSuppressedBy(
 				beforeLease,
 				failedAtMs,
-				this.#now(),
+				beforeLeaseNowMs,
 			) !== undefined
 		) {
 			return { providerId: account.providerId, status: "not-due" };
@@ -1098,15 +1085,17 @@ export class UsageFetcher {
 		const leaseGuard: AntigravityLeaseGuard = { lease, handedOff: false };
 		try {
 			// Step 7: the same checks again, now that nobody else can write.
+			const underLeaseNowMs = this.#now();
 			const underLease = this.#sharedStore.latestAttempt(
 				account.providerId,
 				account.family,
+				underLeaseNowMs,
 			);
 			if (
 				this.#failureRefreshSuppressedBy(
 					underLease,
 					failedAtMs,
-					this.#now(),
+					underLeaseNowMs,
 				) !== undefined
 			) {
 				return { providerId: account.providerId, status: "not-due" };
@@ -1195,6 +1184,7 @@ export class UsageFetcher {
 		const prior = this.#sharedStore.latestAttempt(
 			account.providerId,
 			account.family,
+			nowMs,
 		);
 		// Backoff is checked BEFORE `disabled`, deliberately.
 		//
@@ -1217,12 +1207,7 @@ export class UsageFetcher {
 		// not it was disabled. A retry that fails again simply re-arms the ladder at
 		// its capped rung, so a genuinely dead endpoint is polled at most once per
 		// MAX_USAGE_ATTEMPT_DELAY_MS rather than hammered.
-		const priorDeadline = plausibleAttemptDeadline(prior, nowMs);
-		if (
-			prior !== undefined &&
-			priorDeadline !== undefined &&
-			priorDeadline > nowMs
-		) {
+		if (prior !== undefined && prior.nextAttemptAtMs > nowMs) {
 			await this.#persistWindowGap(
 				account,
 				nowMs,
@@ -1246,21 +1231,17 @@ export class UsageFetcher {
 		}
 		const leaseGuard: AntigravityLeaseGuard = { lease, handedOff: false };
 		try {
-			const current = this.#sharedStore.latestAttempt(
-				account.providerId,
-				account.family,
-			);
 			// Same ordering as the pre-lease check above: an elapsed backoff wins
 			// over a stale `disabled` flag, so a recovered account can be observed
 			// again. Re-read under the lease because a peer may have attempted in
 			// between.
 			const currentNowMs = this.#now();
-			const currentDeadline = plausibleAttemptDeadline(current, currentNowMs);
-			if (
-				current !== undefined &&
-				currentDeadline !== undefined &&
-				currentDeadline > currentNowMs
-			) {
+			const current = this.#sharedStore.latestAttempt(
+				account.providerId,
+				account.family,
+				currentNowMs,
+			);
+			if (current !== undefined && current.nextAttemptAtMs > currentNowMs) {
 				await this.#persistWindowGap(
 					account,
 					this.#now(),
@@ -1654,13 +1635,15 @@ export class UsageFetcher {
 			}
 			// REQ-WINDOW-CADENCE: enforce cross-process 15-minute floor.
 			// Check durable attempt record to prevent peer-process fetch within the window.
+			const cadenceNowMs = this.#now();
 			const prior = this.#sharedStore.latestAttempt(
 				account.providerId,
 				account.family,
+				cadenceNowMs,
 			);
 			if (
 				prior !== undefined &&
-				this.#now() - prior.observedAtMs < WINDOW_SAMPLE_INTERVAL_MS
+				cadenceNowMs - prior.observedAtMs < WINDOW_SAMPLE_INTERVAL_MS
 			) {
 				continue;
 			}