pi-braid-providers 0.0.0-stage → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.ts ADDED
@@ -0,0 +1,910 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { createProvider } from "@earendil-works/pi-ai";
3
+ // `Type` ships with pi-ai's own typebox re-export, so the tool schema adds no
4
+ // dependency to a package that resolves only @earendil-works/* from npm.
5
+ import { Type } from "@earendil-works/pi-ai";
6
+ import {
7
+ completeSimple,
8
+ openAICompletionsApi,
9
+ } from "@earendil-works/pi-ai/compat";
10
+ import type { Model, Provider } from "@earendil-works/pi-ai";
11
+ import {
12
+ AGENT_ZERO_ID,
13
+ BRAID_AUTO_ID,
14
+ AGENT_ZERO_KEY_PREFIX,
15
+ veniceKeyRing,
16
+ registerRoute,
17
+ clearRouteRegistry,
18
+ installDefaultGatewayRoute,
19
+ createRouteRing,
20
+ registerCatalogRoute,
21
+ handleBeforeProviderRequest,
22
+ handleAfterProviderResponse,
23
+ handleMessageEnd,
24
+ publishKeyRingFeedback,
25
+ resolveKeyRingAuth,
26
+ resolveRingForMessage,
27
+ reportKeyRingFailure,
28
+ reportKeyRingSuccess,
29
+ createRotationEngine,
30
+ readProvidersSettingsFromSettings,
31
+ emitProvidersSettingsDiagnostics,
32
+ FAILBACK_PROBE_TIMEOUT_MS,
33
+ ROTATION_WHISPER_TYPE,
34
+ type MessageEndHooks,
35
+ type RouteConfig,
36
+ type RouteDeathVerdict,
37
+ type RouteProbe,
38
+ type RouteProbeVerdict,
39
+ type RotationProbeDeps,
40
+ } from "./ring-lifecycle";
41
+ import {
42
+ VENICE_DIRECT_ID,
43
+ VENICE_DIRECT_KEY_PREFIX,
44
+ VENICE_DIRECT_BASE_URL,
45
+ veniceDirectKeyRing,
46
+ directModelConfigs,
47
+ } from "./venice-direct";
48
+ import { loadVeniceCatalog } from "./venice-catalog.js";
49
+ import type { ChatModelConfig } from "./venice-catalog.js";
50
+ import { keyRingAuth, withKeyRingAuth } from "./ring-provider";
51
+ import { shrinkDoomedPayload, isPresendGuardEnabled } from "./presend-guard";
52
+ import { probeRoute } from "./probe.js";
53
+ import {
54
+ formatRingHealth,
55
+ routeHealth,
56
+ summarizeRouteHealth,
57
+ } from "./ring-health.js";
58
+ import { readRouteState, recordDeath, recordProbe } from "./route-state.js";
59
+ import { registerAutoRouter, type RouteHealthSnapshot } from "./virtual-router";
60
+ import { providerLog, setProvidersLogSink } from "./log";
61
+ import {
62
+ createOutageWatch,
63
+ loadOutageConfig,
64
+ withBreakerApi,
65
+ withBreakerStreams,
66
+ type OutageRouteTarget,
67
+ } from "./outage-watch";
68
+ // Public surface
69
+ // The probe and route-state modules stand on their own — re-export their APIs
70
+ // here so the extension's entry point is the single import site.
71
+ export { probeRoute, DEFAULT_PROBE_TIMEOUT_MS } from "./probe.js";
72
+ export type {
73
+ ProbeDescriptor,
74
+ ProbeDeps,
75
+ ProbeFetch,
76
+ ProbeFetchResponse,
77
+ ProbeOutcome,
78
+ } from "./probe.js";
79
+ export {
80
+ clearFailback,
81
+ readRouteState,
82
+ recordDeath,
83
+ recordFailback,
84
+ recordProbe,
85
+ setWarmModels,
86
+ } from "./route-state.js";
87
+ export {
88
+ claimNotify,
89
+ classifyConnectivityFailure,
90
+ createOutageWatch,
91
+ DEFAULT_OUTAGE_CONFIG,
92
+ formatOutageClock,
93
+ httpReachable,
94
+ loadOutageConfig,
95
+ PROVIDER_OUTAGE_NOTIFY_KEY,
96
+ readOutageNotifySender,
97
+ releaseNotifyClaim,
98
+ renderBlockedText,
99
+ renderOwnerDownText,
100
+ renderOwnerUpText,
101
+ renderStallText,
102
+ resolveOutageConfig,
103
+ withBreakerApi,
104
+ withBreakerStreams,
105
+ } from "./outage-watch";
106
+ export type {
107
+ DownFacts,
108
+ NotifyOutcome,
109
+ OutageConfig,
110
+ OutageRouteTarget,
111
+ OutageWatchDeps,
112
+ ProviderCallGuard,
113
+ ProviderOutageNotifySender,
114
+ ProviderOutageWatch,
115
+ StallFacts,
116
+ } from "./outage-watch";
117
+ export type {
118
+ RouteDeathRecord,
119
+ RouteFailbackRecord,
120
+ RouteProbeRecord,
121
+ RouteState,
122
+ RouteStateEntry,
123
+ } from "./route-state.js";
124
+ // The read-only health surface over the two state files above: a summary for a
125
+ // human or a consumer script, hash-only and never a second writer.
126
+ export {
127
+ formatRingHealth,
128
+ ringHealth,
129
+ routeHealth,
130
+ summarizeRouteHealth,
131
+ } from "./ring-health.js";
132
+ export type {
133
+ DeathFreshness,
134
+ RingEntrySummary,
135
+ RingHealth,
136
+ RingHealthEntry,
137
+ RingHealthOptions,
138
+ RingSummary,
139
+ RouteHealth,
140
+ RouteHealthOptions,
141
+ RouteHealthSummary,
142
+ RouteSummary,
143
+ } from "./ring-health.js";
144
+ export type { RouteProbe } from "./ring-lifecycle";
145
+ // The health-routed virtual model (`braid/auto`): its selection policy is pure and
146
+ // re-exported so a consumer script or a test can drive it without pi.
147
+ export {
148
+ AUTO_MODEL_ID,
149
+ CANONICAL_THINKING_LEVELS,
150
+ buildRoute,
151
+ registerAutoRouter,
152
+ resolveThinkingLevel,
153
+ routeDead,
154
+ routeHealthy,
155
+ routeServesModelId,
156
+ routeSpent,
157
+ selectAnyRoute,
158
+ selectRetryRoute,
159
+ selectRouteByHealth,
160
+ supportedThinkingLevels,
161
+ } from "./virtual-router";
162
+ export type {
163
+ AutoRouteState,
164
+ AutoRouterDeps,
165
+ CanonicalThinkingLevel,
166
+ RetryOptions,
167
+ RouteHealthEntry,
168
+ RouteHealthSnapshot,
169
+ RouteRingHealth,
170
+ RouteSelection,
171
+ RouterRequest,
172
+ SelectOptions,
173
+ ThinkingProfile,
174
+ } from "./virtual-router";
175
+
176
+ // Model Conversion
177
+ // The catalog's chat model config is missing `api`, `provider`, and `baseUrl`
178
+ // (required by Model<TApi>). createProvider fills `baseUrl` from its own field,
179
+ // but Model still requires it. We add the provider id and baseUrl here.
180
+
181
+ function toModels(
182
+ providerId: string,
183
+ baseUrl: string,
184
+ configs: readonly ChatModelConfig[],
185
+ ): Model<"openai-completions">[] {
186
+ return configs.map((c) => ({
187
+ id: c.id,
188
+ name: c.name,
189
+ api: (c.api ?? "openai-completions") as "openai-completions",
190
+ provider: providerId,
191
+ baseUrl: c.baseUrl ?? baseUrl,
192
+ reasoning: c.reasoning,
193
+ thinkingLevelMap: c.thinkingLevelMap,
194
+ input: c.input,
195
+ cost: c.cost,
196
+ contextWindow: c.contextWindow,
197
+ maxTokens: c.maxTokens,
198
+ headers: c.headers,
199
+ compat: c.compat as Model<"openai-completions">["compat"],
200
+ }));
201
+ }
202
+
203
+ // The route table when settings carry no `routes` key: today's pair (the agent-zero
204
+ // gateway and the venice-direct route), in that order. A configured `routes`
205
+ // array supersedes it entirely.
206
+ const DEFAULT_ROUTES: readonly RouteConfig[] = [
207
+ { provider: AGENT_ZERO_ID, keys: AGENT_ZERO_KEY_PREFIX },
208
+ { provider: VENICE_DIRECT_ID, keys: VENICE_DIRECT_KEY_PREFIX },
209
+ ];
210
+
211
+ // Provider id of the health-routed virtual entry (`opencode-go/auto`). Unlike
212
+ // the route ids this package owns, the
213
+ // provider definition is pi-ai's and this build re-points its auth at the
214
+ // route's ring, so the literal sits with the composition root's own table
215
+ // handling rather than in a route module: the entry exists only when
216
+ // `braid.providers.routes` names a provider pi-ai ships, and every physical
217
+ // model id the entry's collision check reads comes from that definition,
218
+ // never from this file.
219
+ const OPENCODE_GO_ID = "opencode-go";
220
+
221
+ // Key Ring Auth
222
+ // auth.apiKey.resolve is called by pi-ai's Models.getAuth() at request time,
223
+ // BEFORE before_provider_request fires. This is the correct interception point
224
+ // for dynamic key selection — the resolved key goes into the request's auth
225
+ // header, not the request body. keyRingAuth (and the re-pointing of a pi-ai
226
+ // provider definition onto a ring) lives in ring-provider.ts.
227
+
228
+ /**
229
+ * pi-ai's provider catalog, resolved only when a route needs it. A route whose
230
+ * provider this package does not build itself is served by pi-ai's own
231
+ * definition, which the ring has to be re-pointed at (ring-provider.ts).
232
+ * Importing the catalog pulls in every provider module, so the default pair —
233
+ * which needs none of it — pays nothing for it.
234
+ */
235
+ async function loadBuiltinProviderCatalog(): Promise<Map<string, Provider>> {
236
+ const { builtinProviders } =
237
+ await import("@earendil-works/pi-ai/providers/all");
238
+ return new Map(builtinProviders().map((provider) => [provider.id, provider]));
239
+ }
240
+
241
+ // rotation glue
242
+ // The engine (state + walk + decision) lives in ring-lifecycle.ts; this glue
243
+ // binds it to pi-core mechanics: model lookup via the event ctx's
244
+ // modelRegistry, the session-only switch via ExtensionAPI.setModel (returns
245
+ // false when the model is unknown or auth is unconfigured → the walk skips the
246
+ // route), and the ONE whisper via ExtensionAPI.sendMessage (customType
247
+ // "provider-rotation", deliverAs nextTurn — non-waking, mirrors the
248
+ // watchdog-recovery family; providers cannot import core's sendTrackedMessage;
249
+ // the engine's one-shot flags guarantee exactly-once). The engine is created in
250
+ // the factory closure (one rotation episode per extension load; /reload re-runs
251
+ // the factory → fresh state) and reset on session_start so a fresh session
252
+ // re-probes from the top of the order. The fail-back probe rides the same
253
+ // seams at turn_end (buildRotationProbeDeps below).
254
+
255
+ /** message_end hooks: the engine's death entry point (key, shape and WAF-repeat classes). */
256
+ function rotationMessageEndHooks(
257
+ engine: ReturnType<typeof createRotationEngine>,
258
+ pi: ExtensionAPI,
259
+ ctx: any,
260
+ ): MessageEndHooks {
261
+ return {
262
+ rotation: {
263
+ onRingExhausted: (providerId: string, errText: string, modelId: string) =>
264
+ engine.maybeEngage(
265
+ providerId,
266
+ errText,
267
+ modelId,
268
+ rotationEngageDeps(pi, ctx),
269
+ ),
270
+ noteWafBlock: (providerId: string, modelId: string) =>
271
+ engine.noteWafBlock(providerId, modelId),
272
+ },
273
+ };
274
+ }
275
+
276
+ /** The rotation whisper sink — the engine's ONE owner-visible message channel. */
277
+ function rotationWhisperSink(pi: ExtensionAPI): (text: string) => void {
278
+ return (text: string) => {
279
+ try {
280
+ pi.sendMessage(
281
+ {
282
+ customType: ROTATION_WHISPER_TYPE,
283
+ content: [{ type: "text", text }],
284
+ display: true,
285
+ },
286
+ { deliverAs: "nextTurn" },
287
+ );
288
+ } catch {
289
+ // The whisper channel must never break the LLM path.
290
+ }
291
+ };
292
+ }
293
+
294
+ /**
295
+ * Session-model swap shared by the engage and the fail-back.
296
+ * modelRegistry.find scopes by provider, so the same model id resolves per
297
+ * route. Unknown model id → inert; a rejected setModel (rare: listener errors)
298
+ * maps to the inert path too — a failed engage must degrade to today's
299
+ * behavior, never surface as an unhandled extension error.
300
+ */
301
+ function rotationSetModel(
302
+ pi: ExtensionAPI,
303
+ ctx: any,
304
+ ): (provider: string, model: string) => Promise<boolean> {
305
+ return async (provider: string, model: string) => {
306
+ const modelObj = ctx?.modelRegistry?.find(provider, model);
307
+ if (!modelObj) return false; // unknown model id → inert
308
+ return pi.setModel(modelObj).catch(() => false);
309
+ };
310
+ }
311
+
312
+ /** Engage deps for the engine, built from the event's own ctx. */
313
+ function rotationEngageDeps(pi: ExtensionAPI, ctx: any) {
314
+ return {
315
+ setModel: rotationSetModel(pi, ctx),
316
+ notify: rotationWhisperSink(pi),
317
+ };
318
+ }
319
+
320
+ // Fail-back probe glue (guard G1: one-way latch)
321
+ // The engine owns the decision and the cadence (ring-lifecycle.ts); this glue
322
+ // supplies the mechanics. The probe is ONE minimal completion on the PRIMARY
323
+ // route's model object (same Model the registry serves, same auth resolution
324
+ // as any direct LLM call), so success is meaningful: auth, quota and model
325
+ // availability all verified on the exact production path. Its outcome feeds
326
+ // the direct-call ring-feedback path (reportKeyRing*), so the key ring stays
327
+ // honest: success heals backoff, a key-rotation failure exhausts + persists
328
+ // (hash-only), a WAF/edge block leaves the key alone. The probe writes NO
329
+ // history, emits NO marker, and is bounded by the engine's interval + its own
330
+ // timeout — nothing else in the session sees it.
331
+ function buildRotationProbeDeps(pi: ExtensionAPI, ctx: any): RotationProbeDeps {
332
+ // A one-word prompt capped at a tiny completion: the probe tests the
333
+ // ROUTE, not the model — a length/aborted-capped stop proves it as well
334
+ // as a full answer would.
335
+ const PROBE_PROMPT = "ping";
336
+ const PROBE_MAX_TOKENS = 16;
337
+ return {
338
+ probe: async (source: string, modelId: string): Promise<boolean> => {
339
+ const modelObj = ctx?.modelRegistry?.find(source, modelId);
340
+ if (!modelObj) return false; // primary model vanished from the registry
341
+ const ring = resolveRingForMessage(source, modelId);
342
+ const auth = ring ? resolveKeyRingAuth(source, ring) : undefined;
343
+ try {
344
+ const msg = await completeSimple(
345
+ modelObj,
346
+ {
347
+ messages: [
348
+ { role: "user", content: PROBE_PROMPT, timestamp: Date.now() },
349
+ ],
350
+ },
351
+ {
352
+ apiKey: auth?.auth.apiKey,
353
+ maxTokens: PROBE_MAX_TOKENS,
354
+ temperature: 0,
355
+ maxRetries: 0, // single-shot: the probe's own interval is the retry budget
356
+ signal: AbortSignal.timeout(FAILBACK_PROBE_TIMEOUT_MS),
357
+ },
358
+ );
359
+ const errText =
360
+ msg?.stopReason === "error" ? String(msg.errorMessage ?? "") : "";
361
+ if (errText) {
362
+ reportKeyRingFailure(modelId, source, errText);
363
+ return false;
364
+ }
365
+ reportKeyRingSuccess(modelId, source);
366
+ return true;
367
+ } catch (err) {
368
+ reportKeyRingFailure(
369
+ modelId,
370
+ source,
371
+ err instanceof Error ? err.message : String(err),
372
+ );
373
+ return false;
374
+ }
375
+ },
376
+ setModel: rotationSetModel(pi, ctx),
377
+ notify: rotationWhisperSink(pi),
378
+ };
379
+ }
380
+
381
+ // Virtual health router snapshot
382
+ // The ONE fs read behind `braid/auto`: the route store's facts joined with each
383
+ // route's ring summary, projected into the pure shape virtual-router.ts walks.
384
+ // A route whose ring file is absent reports `ring: null` (never exhausted), so
385
+ // the policy fails open exactly as the auxiliary path's `routeUsable` does. The
386
+ // route config supplies attribution (modelIds + models map); nothing here names
387
+ // a provider or a model.
388
+ function buildAutoRouteSnapshot(
389
+ routes: readonly RouteConfig[],
390
+ ): RouteHealthSnapshot {
391
+ const routeState = readRouteState();
392
+ const health = routeHealth({
393
+ providers: routes.map((route) => route.provider),
394
+ routeState,
395
+ });
396
+ const byProvider = new Map(health.map((h) => [h.provider, h] as const));
397
+ return {
398
+ routes: routes.map((route) => {
399
+ const summary = byProvider.get(route.provider);
400
+ const entry = routeState.routes[route.provider];
401
+ const ring =
402
+ summary && summary.ring.present
403
+ ? {
404
+ usable: summary.ring.entries.filter((e) => !e.exhausted).length,
405
+ total: summary.ring.entries.length,
406
+ }
407
+ : null;
408
+ return {
409
+ provider: route.provider,
410
+ ring,
411
+ deathClass: entry?.deathClass ?? null,
412
+ deathAt: entry?.deathAt ?? 0,
413
+ deathModelId: entry?.deathModelId ?? null,
414
+ modelIds: route.modelIds ?? [],
415
+ models: route.models ?? {},
416
+ };
417
+ }),
418
+ };
419
+ }
420
+
421
+ export default async function (pi: ExtensionAPI) {
422
+ // Direct-call feed-back
423
+ // Publish the ring-feedback handler into the process-global slot core's
424
+ // callLlm and contrib's vision wrapper read, so a direct (non-message_end)
425
+ // 429/403 exhausts + rotates the correct ring (see ring-lifecycle.ts). Done
426
+ // at factory load so it is available before any session runs; the notify
427
+ // sink is only bound at session_start, so pre-session warns stay silent
428
+ // (consistent with existing providerLog behavior).
429
+ publishKeyRingFeedback();
430
+
431
+ // Read-only ring/route health tool
432
+ // The durable answer to "how many keys has each ring got left, and when
433
+ // does the exhausted one come back?" without opening the state files by
434
+ // hand. Read-only by construction, in three layers: ring-health.ts reads and
435
+ // never writes (no lock, no temp file, no migration), the handler adds no
436
+ // probe, no rotation and no provider request, and the rendered text comes
437
+ // from a summary that copies counts and timestamps only - a key hash has no
438
+ // seat in the output, so it cannot leak into the session log. The death
439
+ // marker is no second opinion either: the window is the resolved setting the
440
+ // router is built with, and the age rule is the router's own predicate.
441
+ pi.registerTool({
442
+ name: "ring_health",
443
+ label: "Ring health",
444
+ promptSnippet: "Show key-ring and route health (read-only)",
445
+ description:
446
+ "Report the health of the LLM key rings and routes: per provider, the " +
447
+ "ring revision, save time, active key index, usable/total key counts " +
448
+ "and each key's exhausted/usable state with its exhaustion time and " +
449
+ "retry count, plus the route's last recorded probe state, headroom, " +
450
+ "remaining balance and reset time, and a recorded death with whether " +
451
+ "the freshness window still makes it act, plus the configured route " +
452
+ "order (preference), first to last. Counts and timestamps only - " +
453
+ "never key material. Strictly read-only: no probe, no rotation, no " +
454
+ "provider request, no write to any state file.",
455
+ parameters: Type.Object({}),
456
+ execute: async () => {
457
+ const health = routeHealth();
458
+ // The same resolved window the rotation engine's death gate walks with
459
+ // (see registerAutoRouter below), so the surface and the gate agree.
460
+ const freshness = { freshnessMs: providersSettings.probeFreshnessMs };
461
+ // The order line states the configured route table - the array the
462
+ // rotation engine is built from (array order IS the rotation order,
463
+ // see registerAutoRouter below). The report's own order is a union of
464
+ // route-state keys and ring files, which is not a preference order.
465
+ const order = routes.map((route) => route.provider);
466
+ return {
467
+ content: [
468
+ {
469
+ type: "text" as const,
470
+ text: formatRingHealth(health, freshness, order),
471
+ },
472
+ ],
473
+ details: { routes: summarizeRouteHealth(health, freshness) },
474
+ };
475
+ },
476
+ });
477
+
478
+ // Register Providers via createProvider
479
+ // createProvider builds a full Provider object with auth.apiKey.resolve that
480
+ // runs at request time. pi.registerProvider(provider) routes through
481
+ // registerNativeProvider, which uses the provider's auth resolution directly.
482
+ // The key ring (veniceKeyRing) lives in ring-lifecycle.ts.
483
+
484
+ // Venice (userland catalog seam)
485
+ // The venice model catalog + gateway URL are owner-private and live in the
486
+ // userland catalog file (see venice-catalog.ts). Without the file the
487
+ // provider is not registered — the key-ring plumbing still attributes any
488
+ // venice model ids that appear in events, which is all it needs.
489
+ const veniceCatalog = loadVeniceCatalog();
490
+ // Route registration is settings-driven. With no `routes` key, today's pair
491
+ // is the default (byte-identical to a build without routes); a configured
492
+ // array supersedes it, in array order.
493
+ const providersSettings = readProvidersSettingsFromSettings();
494
+ const routes: readonly RouteConfig[] = providersSettings.routesConfigured
495
+ ? providersSettings.routes
496
+ : DEFAULT_ROUTES;
497
+ // The built-in gateway entry is a fallback, not a constant: with an explicit
498
+ // route table the registration table is rebuilt from the configured routes
499
+ // alone, so a route the table does not name is neither attributed nor rotated
500
+ // to. Without one the fallback is (re)installed — the default pair's
501
+ // behavior.
502
+ if (providersSettings.routesConfigured) clearRouteRegistry();
503
+ else installDefaultGatewayRoute();
504
+ // A configured route opts into the Venice payload tweak through its own
505
+ // descriptor; the default pair IS the Venice pair, so it keeps the tweak.
506
+ const defaultVenicePayload = !providersSettings.routesConfigured;
507
+ const catalogModelIds = (veniceCatalog?.models ?? []).map((m) => m.id);
508
+
509
+ // A route whose provider is built from the Venice catalog (agent-zero, venice-direct)
510
+ // registers its provider here. A route for any other provider is
511
+ // served by pi-ai's own first-party definition, which stays resolvable
512
+ // through pi's model registry (ctx.modelRegistry.find) — but that definition
513
+ // resolves its key from a bare env var, a key source beside the ring. So the
514
+ // definition is re-registered with its api-key auth re-pointed at the route's
515
+ // ring (ring-provider.ts): one key source per route, and a spent key walks
516
+ // the ring on the next request. Either way the route enters the registration
517
+ // table with its keys prefix, its model ids (the catalog's own ids for the
518
+ // Venice routes, plus the descriptor's) and its model map. Attribution and
519
+ // the payload tweak follow the owning route's descriptor; no route is
520
+ // recognized by a built-in model-id literal.
521
+ //
522
+ // The venice-direct route is registered whenever the catalog exists; without
523
+ // a VENICE_API_KEY credential its auth resolver stays unconfigured and an
524
+ // engage degrades to the one-shot inert notice.
525
+ //
526
+ // The pi-ai catalog is fetched only when a route actually needs it (a route
527
+ // this package does not build itself); the default pair pays nothing for it.
528
+ // A route pi-ai does not ship either is left exactly as it was: another
529
+ // extension may own that provider, and this package has nothing to re-point.
530
+ const needsBuiltinCatalog = routes.some(
531
+ (route) =>
532
+ route.provider !== AGENT_ZERO_ID && route.provider !== VENICE_DIRECT_ID,
533
+ );
534
+ const builtinCatalog = needsBuiltinCatalog
535
+ ? await loadBuiltinProviderCatalog()
536
+ : new Map<string, Provider>();
537
+
538
+ // Outage watch
539
+ // One watcher per extension load. Its targets are the configured routes'
540
+ // own base URLs (a bounded reachability probe), read from the descriptors
541
+ // this loop is about to register; no provider id or host literal lives in
542
+ // the watcher. Load-time settings, read once like the route order itself:
543
+ // braid.providers.outage. The watcher is out-of-loop (its timer does not
544
+ // depend on a turn), which is what lets it alert the owner while a session
545
+ // is held in a retry storm.
546
+ const outageTargets: OutageRouteTarget[] = [];
547
+ for (const route of routes) {
548
+ if (route.provider === AGENT_ZERO_ID) {
549
+ if (veniceCatalog)
550
+ outageTargets.push({
551
+ providerId: AGENT_ZERO_ID,
552
+ url: veniceCatalog.baseUrl,
553
+ });
554
+ continue;
555
+ }
556
+ if (route.provider === VENICE_DIRECT_ID) {
557
+ if (veniceCatalog)
558
+ outageTargets.push({
559
+ providerId: VENICE_DIRECT_ID,
560
+ url: VENICE_DIRECT_BASE_URL,
561
+ });
562
+ continue;
563
+ }
564
+ const builtin = builtinCatalog.get(route.provider);
565
+ outageTargets.push({ providerId: route.provider, url: builtin?.baseUrl });
566
+ }
567
+ const outage = createOutageWatch({
568
+ targets: outageTargets,
569
+ config: loadOutageConfig(),
570
+ });
571
+
572
+ // Diagnostics that need the notify sink, which only exists from the first
573
+ // session_start (the same channel the settings and router diagnostics use).
574
+ const ringProviderDiagnostics: string[] = [];
575
+
576
+ // Probe collection: a route that declares a status capability is probed
577
+ // once below, after registration. Routes without one are never probed.
578
+ const probeJobs: Array<{
579
+ providerId: string;
580
+ descriptor: RouteProbe;
581
+ ring: ReturnType<typeof createRouteRing>;
582
+ }> = [];
583
+
584
+ for (const route of routes) {
585
+ if (route.provider === AGENT_ZERO_ID) {
586
+ if (!veniceCatalog) continue; // no catalog ⇒ nothing to register (the fallback entry stands).
587
+ pi.registerProvider(
588
+ createProvider({
589
+ id: AGENT_ZERO_ID,
590
+ name: "Venice (agent-zero proxy)",
591
+ baseUrl: veniceCatalog.baseUrl,
592
+ auth: { apiKey: keyRingAuth("Venice API key", veniceKeyRing) },
593
+ models: toModels(
594
+ AGENT_ZERO_ID,
595
+ veniceCatalog.baseUrl,
596
+ veniceCatalog.models,
597
+ ),
598
+ api: withBreakerStreams(
599
+ openAICompletionsApi(),
600
+ outage.guard(AGENT_ZERO_ID),
601
+ ),
602
+ }),
603
+ );
604
+ registerCatalogRoute(
605
+ route,
606
+ catalogModelIds,
607
+ veniceKeyRing,
608
+ route.venicePayload ?? defaultVenicePayload,
609
+ );
610
+ if (route.probe) {
611
+ probeJobs.push({
612
+ providerId: route.provider,
613
+ descriptor: route.probe,
614
+ ring: veniceKeyRing,
615
+ });
616
+ }
617
+ continue;
618
+ }
619
+ if (route.provider === VENICE_DIRECT_ID) {
620
+ if (!veniceCatalog) continue;
621
+ pi.registerProvider(
622
+ createProvider({
623
+ id: VENICE_DIRECT_ID,
624
+ name: "Venice (direct)",
625
+ baseUrl: VENICE_DIRECT_BASE_URL,
626
+ auth: {
627
+ apiKey: keyRingAuth("Venice API key", veniceDirectKeyRing),
628
+ },
629
+ models: toModels(
630
+ VENICE_DIRECT_ID,
631
+ VENICE_DIRECT_BASE_URL,
632
+ directModelConfigs(veniceCatalog.models),
633
+ ),
634
+ api: withBreakerStreams(
635
+ openAICompletionsApi(),
636
+ outage.guard(VENICE_DIRECT_ID),
637
+ ),
638
+ }),
639
+ );
640
+ registerCatalogRoute(
641
+ route,
642
+ catalogModelIds,
643
+ veniceDirectKeyRing,
644
+ route.venicePayload ?? defaultVenicePayload,
645
+ );
646
+ if (route.probe) {
647
+ probeJobs.push({
648
+ providerId: route.provider,
649
+ descriptor: route.probe,
650
+ ring: veniceDirectKeyRing,
651
+ });
652
+ }
653
+ continue;
654
+ }
655
+ const ring = createRouteRing(route);
656
+ const builtin = builtinCatalog.get(route.provider);
657
+ const ringProvider = builtin ? withKeyRingAuth(builtin, ring) : null;
658
+ if (ringProvider) {
659
+ pi.registerProvider(
660
+ withBreakerApi(ringProvider, outage.guard(route.provider)),
661
+ );
662
+ } else if (builtin) {
663
+ // The definition exists but carries no api-key auth to back with the ring
664
+ // (an OAuth-only provider). Leaving it alone is correct — pi resolves its
665
+ // OAuth credential — but a route the ring cannot serve is a fact the owner
666
+ // should hear, because key exhaustion on it is not something rotation can
667
+ // repair.
668
+ ringProviderDiagnostics.push(
669
+ `route "${route.provider}" keeps pi-ai's own auth: its provider ` +
670
+ `definition has no api-key auth to back with the ring (prefix ` +
671
+ `${route.keys})`,
672
+ );
673
+ }
674
+ registerRoute({
675
+ providerId: route.provider,
676
+ keys: route.keys,
677
+ modelIds: route.modelIds ?? [],
678
+ models: route.models,
679
+ probe: route.probe,
680
+ venicePayload: route.venicePayload ?? defaultVenicePayload,
681
+ ring,
682
+ });
683
+ if (route.probe) {
684
+ probeJobs.push({
685
+ providerId: route.provider,
686
+ descriptor: route.probe,
687
+ ring,
688
+ });
689
+ }
690
+ }
691
+
692
+ // Session-start probe (fire-and-forget)
693
+ // ONE non-billable status read per route that declares a probe capability,
694
+ // recorded so the next session inherits what this one observed. Deliberately
695
+ // not awaited (registration must never block on the network) and never
696
+ // fatal (probeRoute rejects on nothing). With no probe descriptors — the
697
+ // default routes carry none — this loop body never runs and registration is
698
+ // byte-identical to a build without the feature.
699
+ for (const job of probeJobs) {
700
+ const providerId = job.providerId;
701
+ void probeRoute(providerId, job.descriptor, job.ring.getActiveKey())
702
+ .then((outcome) => recordProbe(providerId, outcome))
703
+ .catch(() => {
704
+ // A probe is diagnostics; it must never surface as an unhandled
705
+ // rejection or change the registration outcome.
706
+ });
707
+ }
708
+
709
+ // Route-order rotation engine
710
+ // Created AFTER registration completes: the walk consults the registration
711
+ // table for each route's ring, model ids and model map, and the order is the
712
+ // same routes array the registration loop just used (array order IS the
713
+ // rotation order). One engine per extension load (/reload re-runs the
714
+ // factory → fresh state); session_start resets it so a fresh session re-probes
715
+ // the primary. In-memory only: no rotation state crosses sessions (the
716
+ // session's own model_change entry persists the switch naturally).
717
+ //
718
+ // Probe steering and the route-death memory are handed in as DATA: this
719
+ // closure resolves the recorded verdicts through readRouteState (the state
720
+ // store's only reader) once per engage, so the engine stays provider-blind
721
+ // and never touches the file, and it binds the store's own writer so a shape
722
+ // rejection (a (route, request) fact, no key at fault) is persisted hash-free
723
+ // and outlives the session. The freshness bound is settings, read at load
724
+ // like the order itself.
725
+ const engine = createRotationEngine({
726
+ order: routes.map((route) => route.provider),
727
+ probeFreshnessMs: providersSettings.probeFreshnessMs,
728
+ probeStates: () => {
729
+ const states = new Map<string, RouteProbeVerdict>();
730
+ for (const [routeId, entry] of Object.entries(readRouteState().routes)) {
731
+ if (entry.lastProbe) states.set(routeId, entry.lastProbe);
732
+ }
733
+ return states;
734
+ },
735
+ routeDeaths: () => {
736
+ const deaths = new Map<string, RouteDeathVerdict>();
737
+ for (const [routeId, entry] of Object.entries(readRouteState().routes)) {
738
+ if (entry.deathClass === null) continue;
739
+ deaths.set(routeId, {
740
+ class: entry.deathClass,
741
+ modelId: entry.deathModelId,
742
+ status: entry.deathStatus,
743
+ at: entry.deathAt,
744
+ });
745
+ }
746
+ return deaths;
747
+ },
748
+ recordRouteDeath: (providerId, death) => recordDeath(providerId, death),
749
+ });
750
+
751
+ // Health-routed virtual model (`braid/auto`)
752
+ // One selectable model that answers each request with the first healthy route
753
+ // in the configured order, so the per-spawn route decision moves to the one
754
+ // seam pi asks for it. The entry lives under the package's own `braid`
755
+ // namespace because the auto route spans several providers (opencode-go, agent-zero,
756
+ // venice-direct, openrouter); the gateway route keeps its `agent-zero` id
757
+ // for itself. Registered only when this build actually carries the agent-zero route (its
758
+ // catalog exists and the route table names it); the virtual model
759
+ // definition itself carries no limits or input types, so pi reads the
760
+ // physical model it routed to. The skip diagnostics are emitted at
761
+ // session_start, where the notify sink exists.
762
+ const virtualRouterDiagnostics: string[] = [];
763
+ const agentZeroRoutePresent = routes.some(
764
+ (route) => route.provider === AGENT_ZERO_ID,
765
+ );
766
+ if (veniceCatalog && agentZeroRoutePresent) {
767
+ registerAutoRouter(pi, {
768
+ provider: BRAID_AUTO_ID,
769
+ // `braid` is a virtual-only namespace: this package registers no physical
770
+ // model under it, so there is no physical list to consult and nothing
771
+ // this entry could shadow. pi-core itself throws when a virtual id
772
+ // collides with a physical model of the same provider at registration
773
+ // time, so an existing `braid/auto` would fail loudly, never be hidden.
774
+ hasPhysicalModel: () => false,
775
+ readSnapshot: () => buildAutoRouteSnapshot(routes),
776
+ logicalModelId: () => providersSettings.defaultModel,
777
+ freshnessMs: providersSettings.probeFreshnessMs,
778
+ log: (message) => virtualRouterDiagnostics.push(message),
779
+ });
780
+ }
781
+
782
+ // Health-routed virtual model (`opencode-go/auto`)
783
+ // The same router, a second seat: a session pinned to a concrete
784
+ // opencode-go model has no failover path while that route keeps rejecting
785
+ // its requests. The entry is registered under the route table's own id
786
+ // and only when that table names the route; the collision check reads the
787
+ // model list of the pi-ai definition this build re-points at the route's
788
+ // ring, so a physical `auto` added upstream would win and this entry skips
789
+ // itself with one diagnostic - the same rule the braid entry follows.
790
+ const opencodeGoDefinition = builtinCatalog.get(OPENCODE_GO_ID);
791
+ if (
792
+ opencodeGoDefinition &&
793
+ routes.some((route) => route.provider === OPENCODE_GO_ID)
794
+ ) {
795
+ const physicalModelIds = new Set(
796
+ opencodeGoDefinition.getModels().map((m) => m.id),
797
+ );
798
+ registerAutoRouter(pi, {
799
+ provider: OPENCODE_GO_ID,
800
+ hasPhysicalModel: (modelId) => physicalModelIds.has(modelId),
801
+ readSnapshot: () => buildAutoRouteSnapshot(routes),
802
+ logicalModelId: () => providersSettings.defaultModel,
803
+ freshnessMs: providersSettings.probeFreshnessMs,
804
+ log: (message) => virtualRouterDiagnostics.push(message),
805
+ });
806
+ }
807
+
808
+ // TUI notify sink (native pi-core pattern)
809
+ // The factory's ExtensionAPI has no `ui`; the session_start handler is the
810
+ // first context carrying ctx.ui.notify. In RPC/print/headless runs pi hands
811
+ // notify a no-op, so these lines are inert there; cleared on shutdown so no
812
+ // stale reference outlives the session. All provider diagnostics (key-ring
813
+ // + ring-lifecycle warns) route through this sink — never console.* (see
814
+ // log.ts).
815
+ pi.on("session_start", (_event, _ctx) => {
816
+ engine.reset();
817
+ setProvidersLogSink(
818
+ _ctx?.ui?.notify ? _ctx.ui.notify.bind(_ctx.ui) : undefined,
819
+ );
820
+ // Settings diagnostics need the notify sink, which only exists from here
821
+ // (the reader runs before the first session_start). Throttled, so a
822
+ // resumed session does not repeat them within the window.
823
+ emitProvidersSettingsDiagnostics(
824
+ readProvidersSettingsFromSettings().diagnostics,
825
+ );
826
+ for (const diagnostic of virtualRouterDiagnostics) {
827
+ providerLog("warn", "providers/virtual-router", diagnostic);
828
+ }
829
+ for (const diagnostic of ringProviderDiagnostics) {
830
+ providerLog("warn", "providers/ring-provider", diagnostic);
831
+ }
832
+ });
833
+ pi.on("session_shutdown", (_event, _ctx) => {
834
+ setProvidersLogSink(undefined);
835
+ });
836
+
837
+ // Event Wiring
838
+ // All handler logic (including per-event key-ring attribution) lives in
839
+ // ring-lifecycle.ts so it can be tested without loading pi-ai at runtime.
840
+
841
+ /** Session identity for the outage watcher's stall spans; never throws. */
842
+ function outageSessionKey(ctx: any): string {
843
+ try {
844
+ const file = ctx?.sessionManager?.getSessionFile?.();
845
+ if (typeof file === "string" && file) return file;
846
+ } catch {
847
+ // A replaced session context can throw on access; cwd is the fallback.
848
+ }
849
+ return typeof ctx?.cwd === "string" && ctx.cwd ? ctx.cwd : "unknown";
850
+ }
851
+
852
+ // Model-id → catalog context window for the pre-send guard.
853
+ // Built once at factory load from the catalog this package owns (venice-catalog.ts).
854
+ const presendContextWindows = new Map<string, number>();
855
+ for (const m of veniceCatalog?.models ?? []) {
856
+ if (typeof m.contextWindow === "number" && m.contextWindow > 0) {
857
+ presendContextWindows.set(m.id, m.contextWindow);
858
+ }
859
+ }
860
+
861
+ pi.on("before_provider_request", async (event: any) => {
862
+ // Ring-lifecycle first (WAF/key shaping), then the pre-send guard on
863
+ // the (possibly reshaped) payload. The guard no-ops unless the payload is
864
+ // DOOMED for a KNOWN model; its returned payload (when present) replaces
865
+ // the outgoing body per pi-core's emitBeforeProviderRequest semantics.
866
+ const shaped = handleBeforeProviderRequest(event.payload);
867
+ const outgoing = shaped ?? event.payload;
868
+ try {
869
+ if (!isPresendGuardEnabled()) return shaped;
870
+ const guard = shrinkDoomedPayload(outgoing, {
871
+ resolveContextWindow: (modelId) => presendContextWindows.get(modelId),
872
+ });
873
+ return guard?.payload ?? shaped;
874
+ } catch {
875
+ // The guard must never break the send path.
876
+ return shaped;
877
+ }
878
+ });
879
+
880
+ pi.on("after_provider_response", async (event: any) =>
881
+ handleAfterProviderResponse(event),
882
+ );
883
+
884
+ pi.on("message_end", async (event: any, ctx: any) => {
885
+ // Order matters: the outage feed reads the ORIGINAL error text (a
886
+ // ring-lifecycle replacement can rewrite it), and a watcher fault must
887
+ // never break the key-ring path it sits beside.
888
+ try {
889
+ outage.observe(event?.message, outageSessionKey(ctx));
890
+ } catch {
891
+ // The feed is observability; the ring path below owns the event.
892
+ }
893
+ return handleMessageEnd(event, rotationMessageEndHooks(engine, pi, ctx));
894
+ });
895
+
896
+ // Fail-back at the turn boundary (guard G1)
897
+ // The ONLY trigger the fail-back uses: no background timer, no per-request
898
+ // hook. While a rotation episode is active, each settled turn gives the
899
+ // engine one chance to probe the primary (interval-bounded inside the
900
+ // engine); an inert engine (no engage this session) returns null before
901
+ // touching anything, so sessions that never rotate are byte-identical to a
902
+ // build without the feature.
903
+ pi.on("turn_end", async (_event: unknown, ctx: any) => {
904
+ try {
905
+ await engine.maybeFailBack(buildRotationProbeDeps(pi, ctx));
906
+ } catch {
907
+ // A probe failure must never break the turn boundary.
908
+ }
909
+ });
910
+ }