@aeondave/pi-persona 1.15.2

package/src/engine/errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared provider-error recognition for the engine layer's `failureKind` classification.
+ *
+ * The fallback decorator (`fallback.ts`) reroutes ONLY `failureKind === "provider"`, so the
+ * classification decides whether a failure retries the same model id through another provider
+ * route or stops dead. Two producers need the SAME judgment:
+ *  - the in-process engine classifies a THROWN error (a provider API rejection often throws
+ *    before any stream event fires — but a throw is not automatically a provider fault);
+ *  - the child engine classifies a pre-stream death (the provider rejected the request and
+ *    `pi` exited non-zero before emitting a single assistant event — evidence lives in
+ *    stderr/exit text, not in a stream `error` stop reason).
+ *
+ * Conservative by design: only patterns that essentially always mean "the provider rejected
+ * or broke" classify as provider. Anything ambiguous stays "agent" (terminal), because a
+ * wrong reroute burns tokens while a wrong terminal failure is at least honest. Pure.
+ */
+
+const PROVIDER_PATTERNS: readonly RegExp[] = [
+	/\brate.?limit|\b429\b|too many requests/i,
+	/\bquota\b|billing|insufficient.?credits/i,
+	/\b401\b|\b403\b|unauthorized|invalid[\s_-]?api[\s_-]?key/i,
+	/\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout|overloaded|capacity/i,
+	/model.{0,24}(not.{0,8}(supported|found|exist)|does not exist)|unsupported.{0,12}model/i,
+	/\beconnreset\b|\betimedout\b|\beconnrefused\b|socket hang up|fetch failed/i,
+];
+
+/** True when the text is evidence of a PROVIDER-side rejection/outage (not agent behavior). */
+export function looksLikeProviderError(text: string): boolean {
+	return PROVIDER_PATTERNS.some((re) => re.test(text));
+}

package/src/engine/fallback.ts

@@ -0,0 +1,57 @@
+/**
+ * Model provider-fallback decorator. Wraps a `StrategyEngine` so a run that fails with a
+ * PROVIDER error (the model's provider rejected or broke — auth, outage, 5xx, model-not-
+ * supported) may be retried on the SAME model id through a family-compatible provider route.
+ * An unpinned selection may reroute when its provider fails at call time. A provider-qualified
+ * `spec.model` is an explicit billing/provider pin and is strict by default; callers must opt it
+ * into cross-provider recovery.
+ *
+ * Only `failureKind === "provider"` retries. abort / timeout / contract / unknown-agent /
+ * unknown-model / agent failures pass straight through (a different provider can't fix
+ * them). The abort signal is honoured between attempts, so a user stop ends the chain.
+ *
+ * Engine-agnostic and pure over its injected deps (the model list + preferred provider),
+ * so it's testable with a stub engine and a fake registry — no live model.
+ */
+
+import type { ModelLite, ModelRoutingPolicy } from "../core/models.ts";
+import { DEFAULT_MODEL_ROUTING_POLICY, providerFallbacks } from "../core/models.ts";
+import type { AgentRunSpec, StrategyEngine } from "../orchestration/sdk.ts";
+
+export interface FallbackDeps {
+	/** The authenticated model list to draw alternates from (NOT every registry model). */
+	models: ModelLite[];
+	/** The session/loader provider — tried first among alternates (most likely authed). */
+	preferProvider?: string;
+	/** Optional deployment policy for automatic fallback; safe first-party defaults otherwise. */
+	routingPolicy?: ModelRoutingPolicy;
+	/** Explicitly opt a provider-qualified model into cross-provider recovery. */
+	allowCrossProviderFallback?: boolean;
+	/** Notified on each reroute, for transparency: the extension wires this to a warning toast, not
+	 *  a tree/log breadcrumb. */
+	onFallback?: (info: { from: string; to: string; agent: string }) => void;
+}
+
+export function withModelFallback(engine: StrategyEngine, deps: FallbackDeps): StrategyEngine {
+	return {
+		async run(spec, onProgress, signal, onSteerable) {
+			const tried = new Set<string>();
+			let result = await engine.run(spec, onProgress, signal, onSteerable);
+			if (result.modelUsed) tried.add(result.modelUsed);
+			const providerPinned = spec.model?.includes("/") === true;
+			const mayCrossProvider = !providerPinned || deps.allowCrossProviderFallback === true;
+			while (mayCrossProvider && result.failureKind === "provider" && !signal?.aborted) {
+				const from = result.modelUsed ?? spec.model;
+				if (!from) break;
+				const next = providerFallbacks(from, deps.models, deps.preferProvider, deps.routingPolicy ?? DEFAULT_MODEL_ROUTING_POLICY).find((r) => !tried.has(r));
+				if (!next) break;
+				tried.add(next);
+				deps.onFallback?.({ from, to: next, agent: spec.agent });
+				const attempt: AgentRunSpec = { ...spec, model: next };
+				result = await engine.run(attempt, onProgress, signal, onSteerable);
+				if (result.modelUsed) tried.add(result.modelUsed);
+			}
+			return result;
+		},
+	};
+}

package/src/engine/handles.ts

@@ -0,0 +1,21 @@
+/**
+ * Child bus-handle minting — ONE sequence shared by BOTH engines.
+ *
+ * The child engine (`adapter.ts`, via the broker host) and the in-process engine
+ * (`inproc.ts`) register their handles into the SAME session bus, so a counter per
+ * engine module is not enough: a mixed inproc + child pair of the same agent would
+ * mint the same `agent#n`, share one inbox, and the first to settle would unregister
+ * the other, still-running leg.
+ *
+ * Module-level (NOT per-engine): `buildEngine` makes a fresh engine per
+ * delegate/council/flow-phase/async-launch, so a per-closure counter would restart at 0
+ * and collide handles across concurrent runs.
+ */
+
+let globalChildSeq = 0;
+
+/** The next unique bus handle for a child of `agent` (e.g. `scout#3`). */
+export function nextChildHandle(agent: string): string {
+	globalChildSeq += 1;
+	return `${agent}#${globalChildSeq}`;
+}