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/LICENSE +21 -0
- package/README.md +230 -2
- package/failure-translation.ts +142 -0
- package/index.ts +910 -0
- package/key-ring.ts +888 -0
- package/log.ts +126 -0
- package/outage-watch.ts +1023 -0
- package/package.json +53 -4
- package/presend-guard.ts +412 -0
- package/probe.ts +380 -0
- package/ring-health.ts +601 -0
- package/ring-lifecycle.ts +2720 -0
- package/ring-provider.ts +123 -0
- package/route-state.ts +617 -0
- package/state-paths.ts +90 -0
- package/venice-catalog.ts +61 -0
- package/venice-direct.ts +59 -0
- package/virtual-router.ts +614 -0
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
|
+
}
|