@narumitw/pi-goal 0.54.17 → 0.55.1
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/CHANGELOG.md +17 -0
- package/README.md +21 -11
- package/dist/chunks/{chunk-MHW7VEET.ts → chunk-7RO3AIWI.ts} +457 -33
- package/dist/chunks/chunk-7RO3AIWI.ts.map +7 -0
- package/dist/chunks/{chunk-ZLKWPYIF.ts → chunk-OPW4T4QN.ts} +6 -1
- package/dist/chunks/{chunk-ZLKWPYIF.ts.map → chunk-OPW4T4QN.ts.map} +2 -2
- package/dist/chunks/{menu-3AYWQ637.ts → menu-P4DPWLVL.ts} +3 -3
- package/dist/chunks/{settings-ui-RVQTWGJ5.ts → settings-ui-X5XS74CD.ts} +39 -3
- package/dist/chunks/settings-ui-X5XS74CD.ts.map +7 -0
- package/dist/index.ts +14 -8
- package/dist/index.ts.map +2 -2
- package/docs/continuation-lifecycle.md +81 -11
- package/docs/managing-goals.md +18 -0
- package/docs/settings.md +48 -2
- package/package.json +3 -3
- package/src/lifecycle.ts +12 -3
- package/src/runtime.ts +175 -30
- package/src/settings-ui.ts +51 -2
- package/src/settings.ts +9 -0
- package/src/usage-limit-recovery.ts +162 -0
- package/src/usage-reset.ts +309 -0
- package/src/wait.ts +21 -1
- package/dist/chunks/chunk-MHW7VEET.ts.map +0 -7
- package/dist/chunks/settings-ui-RVQTWGJ5.ts.map +0 -7
- /package/dist/chunks/{menu-3AYWQ637.ts.map → menu-P4DPWLVL.ts.map} +0 -0
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { notifyTerminal, truncateNotification } from "./errors.js";
|
|
3
|
+
import type { GoalRuntime, StatusContext } from "./runtime.js";
|
|
4
|
+
import { readUsageReset } from "./usage-reset.js";
|
|
5
|
+
import { type GoalWait, MIN_GOAL_WAIT_DELAY_MS, type UsageLimitScope } from "./wait.js";
|
|
6
|
+
|
|
7
|
+
export const USAGE_LIMIT_RETRY_MS = 15 * 60 * 1000;
|
|
8
|
+
|
|
9
|
+
/** Owns optional quota reads, not a second continuation loop. */
|
|
10
|
+
export class UsageLimitRecovery {
|
|
11
|
+
private query?: { controller: AbortController; waiting: GoalWait };
|
|
12
|
+
|
|
13
|
+
private readonly runtime: GoalRuntime;
|
|
14
|
+
|
|
15
|
+
constructor(runtime: GoalRuntime) {
|
|
16
|
+
this.runtime = runtime;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
cancel() {
|
|
20
|
+
const query = this.query;
|
|
21
|
+
this.query = undefined;
|
|
22
|
+
query?.controller.abort();
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
enter(ctx: StatusContext, errorMessage: string | undefined, origin?: UsageLimitScope) {
|
|
26
|
+
const runtime = this.runtime;
|
|
27
|
+
const goal = runtime.activeGoal;
|
|
28
|
+
if (!goal || !runtime.settings.retryUsageLimits || !runtime.ownsWorkflow(goal)) return false;
|
|
29
|
+
if (origin && !sameUsageLimitScope(origin, usageLimitScope(ctx))) {
|
|
30
|
+
this.stop(ctx, "model changed before usage-limit settlement");
|
|
31
|
+
return true;
|
|
32
|
+
}
|
|
33
|
+
if (
|
|
34
|
+
runtime.enforceAutomaticTurnLimit(ctx, false) ||
|
|
35
|
+
runtime.enforceNoProgressLimit(ctx) ||
|
|
36
|
+
runtime.limitActiveGoalForBudget(ctx, false)
|
|
37
|
+
)
|
|
38
|
+
return true;
|
|
39
|
+
if (!runtime.goalToolsAvailable()) return runtime.pauseGoalForUnavailableTools(ctx, false);
|
|
40
|
+
const waiting: GoalWait = {
|
|
41
|
+
reason: `Provider usage limit${errorMessage ? `: ${truncateNotification(errorMessage)}` : ""}`,
|
|
42
|
+
resumeAt: Date.now() + USAGE_LIMIT_RETRY_MS,
|
|
43
|
+
usageLimit: usageLimitScope(ctx),
|
|
44
|
+
};
|
|
45
|
+
const entered = runtime.enterGoalWait(ctx, goal.id, waiting);
|
|
46
|
+
if (entered?.id !== goal.id || entered.waiting !== waiting || !runtime.ownsWorkflow(entered)) return true;
|
|
47
|
+
notifyTerminal(
|
|
48
|
+
ctx.ui,
|
|
49
|
+
"Goal waiting after provider usage limit. Automatic recovery uses a reset hint when available, otherwise retries in 15 minutes. Pause or clear the Goal to stop recovery.",
|
|
50
|
+
"warning",
|
|
51
|
+
);
|
|
52
|
+
if (runtime.activeGoal?.waiting === waiting && runtime.ownsWorkflow()) this.refreshHint(ctx, goal.id, waiting);
|
|
53
|
+
return true;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
stopIfDisabled(ctx: StatusContext) {
|
|
57
|
+
if (!this.scope() || this.runtime.settings.retryUsageLimits) return false;
|
|
58
|
+
this.stop(ctx, "automatic usage-limit recovery disabled");
|
|
59
|
+
return true;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
modelChanged(ctx: StatusContext) {
|
|
63
|
+
const scope = this.scope();
|
|
64
|
+
if (!scope || sameUsageLimitScope(scope, usageLimitScope(ctx))) return;
|
|
65
|
+
this.stop(ctx, "model changed during usage-limit recovery");
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
matches(ctx: StatusContext, waiting: GoalWait) {
|
|
69
|
+
return !waiting.usageLimit || sameUsageLimitScope(waiting.usageLimit, usageLimitScope(ctx));
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
private scope() {
|
|
73
|
+
const runtime = this.runtime;
|
|
74
|
+
return (
|
|
75
|
+
runtime.activeGoal?.waiting?.usageLimit ??
|
|
76
|
+
runtime.continuationIntent?.usageLimitRetry ??
|
|
77
|
+
runtime.continuationDelivery?.usageLimitRetry ??
|
|
78
|
+
runtime.agentRunUsageLimitRetry ??
|
|
79
|
+
(runtime.goalRecovery?.goalId === runtime.activeGoal?.id ? runtime.goalRecovery?.usageLimitScope : undefined)
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
private stop(ctx: StatusContext, reason: string) {
|
|
84
|
+
const runtime = this.runtime;
|
|
85
|
+
const goal = runtime.activeGoal;
|
|
86
|
+
if (!goal || !runtime.ownsWorkflow(goal)) return;
|
|
87
|
+
runtime.stopActiveGoal(ctx, {
|
|
88
|
+
kind: runtime.agentRunGoalId === goal.id ? "agent_interruption" : "recovery_ended",
|
|
89
|
+
expectedGoalId: goal.id,
|
|
90
|
+
status: "usage_limited",
|
|
91
|
+
reason,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
private refreshHint(ctx: StatusContext, goalId: string, waiting: GoalWait) {
|
|
96
|
+
const session = ctx.sessionManager as { getSessionId?: unknown } | undefined;
|
|
97
|
+
if (!ctx.model || typeof session?.getSessionId !== "function") return;
|
|
98
|
+
const generation = this.runtime.menuGeneration;
|
|
99
|
+
const query = { controller: new AbortController(), waiting };
|
|
100
|
+
this.query = query;
|
|
101
|
+
const current = () =>
|
|
102
|
+
this.query === query &&
|
|
103
|
+
!query.controller.signal.aborted &&
|
|
104
|
+
generation === this.runtime.menuGeneration &&
|
|
105
|
+
this.runtime.settings.retryUsageLimits &&
|
|
106
|
+
this.runtime.activeGoal?.id === goalId &&
|
|
107
|
+
this.runtime.activeGoal.waiting === waiting &&
|
|
108
|
+
this.runtime.ownsWorkflow() &&
|
|
109
|
+
this.matches(ctx, waiting);
|
|
110
|
+
void readUsageReset(
|
|
111
|
+
this.runtime.pi,
|
|
112
|
+
ctx as Pick<ExtensionContext, "sessionManager" | "model">,
|
|
113
|
+
query.controller.signal,
|
|
114
|
+
)
|
|
115
|
+
.then((resetAt) => {
|
|
116
|
+
if (!current()) return;
|
|
117
|
+
this.query = undefined;
|
|
118
|
+
query.controller.abort();
|
|
119
|
+
if (resetAt === undefined) return;
|
|
120
|
+
const goal = this.runtime.activeGoal;
|
|
121
|
+
if (!goal || goal.id !== goalId || goal.waiting !== waiting) return;
|
|
122
|
+
const nextWait = { ...waiting, resumeAt: Math.max(Date.now() + MIN_GOAL_WAIT_DELAY_MS, resetAt) };
|
|
123
|
+
const hintedGoal = { ...goal, waiting: nextWait, updatedAt: Date.now() };
|
|
124
|
+
this.runtime.activeGoal = hintedGoal;
|
|
125
|
+
try {
|
|
126
|
+
this.runtime.persistGoal(hintedGoal);
|
|
127
|
+
} catch {
|
|
128
|
+
if (this.runtime.activeGoal !== hintedGoal || !this.runtime.ownsWorkflow()) return;
|
|
129
|
+
this.runtime.activeGoal = goal;
|
|
130
|
+
try {
|
|
131
|
+
this.runtime.persistGoal(goal);
|
|
132
|
+
} catch {
|
|
133
|
+
// Keep the original in-memory deadline even if storage remains unavailable.
|
|
134
|
+
}
|
|
135
|
+
if (this.runtime.activeGoal === goal && this.runtime.ownsWorkflow()) this.runtime.restoreGoalWaitTimer(ctx);
|
|
136
|
+
return;
|
|
137
|
+
}
|
|
138
|
+
if (
|
|
139
|
+
this.runtime.activeGoal === hintedGoal &&
|
|
140
|
+
this.runtime.ownsWorkflow() &&
|
|
141
|
+
generation === this.runtime.menuGeneration
|
|
142
|
+
)
|
|
143
|
+
this.runtime.restoreGoalWaitTimer(ctx);
|
|
144
|
+
})
|
|
145
|
+
.catch(() => {
|
|
146
|
+
// A stale context, provider failure, or failed publication leaves the
|
|
147
|
+
// persisted fallback in place; no exception escapes an owned task.
|
|
148
|
+
})
|
|
149
|
+
.finally(() => {
|
|
150
|
+
if (this.query === query) this.query = undefined;
|
|
151
|
+
query.controller.abort();
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export function usageLimitScope(ctx: Pick<StatusContext, "model">): UsageLimitScope {
|
|
157
|
+
return { provider: ctx.model?.provider ?? "", model: ctx.model?.id ?? "", api: ctx.model?.api ?? "" };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function sameUsageLimitScope(left: UsageLimitScope, right: UsageLimitScope) {
|
|
161
|
+
return left.provider === right.provider && left.model === right.model && left.api === right.api;
|
|
162
|
+
}
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
|
|
3
|
+
type UsageContext = Pick<ExtensionContext, "sessionManager" | "model">;
|
|
4
|
+
type RecordValue = Record<string, unknown>;
|
|
5
|
+
type Bucket = {
|
|
6
|
+
id: string;
|
|
7
|
+
modelKeys?: string[];
|
|
8
|
+
used?: number;
|
|
9
|
+
remaining?: number;
|
|
10
|
+
limit?: number;
|
|
11
|
+
resetsAt?: number;
|
|
12
|
+
};
|
|
13
|
+
const DEADLINE_MS = 15_000;
|
|
14
|
+
const MAX_TIMESTAMP_MS = 8_640_000_000_000_000;
|
|
15
|
+
const UNITS = new Set(["percent", "usd", "currency", "count"]);
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Read a scheduling hint through the public usage v1 protocol, without retaining a report.
|
|
19
|
+
* Call from session_start or later. The owner must abort on Goal/generation replacement,
|
|
20
|
+
* model/session changes, and shutdown, then revalidate its own ownership after awaiting.
|
|
21
|
+
*/
|
|
22
|
+
export async function readUsageReset(
|
|
23
|
+
pi: Pick<ExtensionAPI, "events">,
|
|
24
|
+
ctx: UsageContext,
|
|
25
|
+
signal: AbortSignal,
|
|
26
|
+
): Promise<number | undefined> {
|
|
27
|
+
try {
|
|
28
|
+
if (signal.aborted) return undefined;
|
|
29
|
+
const session = ctx.sessionManager;
|
|
30
|
+
const sessionId = session.getSessionId();
|
|
31
|
+
const model = ctx.model;
|
|
32
|
+
if (!model?.provider || !model.id || !model.name || typeof sessionId !== "string" || !sessionId) {
|
|
33
|
+
return undefined;
|
|
34
|
+
}
|
|
35
|
+
const provider = model.provider;
|
|
36
|
+
const modelId = model.id;
|
|
37
|
+
const modelName = model.name;
|
|
38
|
+
const snapshot = JSON.stringify(model);
|
|
39
|
+
const startedAt = Date.now();
|
|
40
|
+
const deadline = performance.now() + DEADLINE_MS;
|
|
41
|
+
const current = () =>
|
|
42
|
+
!signal.aborted &&
|
|
43
|
+
performance.now() < deadline &&
|
|
44
|
+
ctx.sessionManager === session &&
|
|
45
|
+
session.getSessionId() === sessionId &&
|
|
46
|
+
ctx.model === model &&
|
|
47
|
+
JSON.stringify(ctx.model) === snapshot;
|
|
48
|
+
|
|
49
|
+
const result = await new Promise<unknown>((resolve) => {
|
|
50
|
+
const controller = new AbortController();
|
|
51
|
+
let open = true;
|
|
52
|
+
let offered = false;
|
|
53
|
+
let done = false;
|
|
54
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
55
|
+
const finish = (value?: unknown) => {
|
|
56
|
+
if (done) return;
|
|
57
|
+
done = true;
|
|
58
|
+
open = false;
|
|
59
|
+
clearTimeout(timer);
|
|
60
|
+
signal.removeEventListener("abort", cancel);
|
|
61
|
+
resolve(value);
|
|
62
|
+
controller.abort();
|
|
63
|
+
};
|
|
64
|
+
const cancel = () => finish();
|
|
65
|
+
try {
|
|
66
|
+
timer = setTimeout(cancel, DEADLINE_MS);
|
|
67
|
+
signal.addEventListener("abort", cancel, { once: true });
|
|
68
|
+
if (signal.aborted) {
|
|
69
|
+
finish();
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
pi.events.emit("usage:query:v1", {
|
|
73
|
+
session,
|
|
74
|
+
sessionId,
|
|
75
|
+
providerId: provider,
|
|
76
|
+
refresh: true,
|
|
77
|
+
signal: controller.signal,
|
|
78
|
+
respond(value: unknown) {
|
|
79
|
+
const accepted = open && !offered && !done;
|
|
80
|
+
if (accepted) offered = true;
|
|
81
|
+
// Observe every offer, including rejected duplicates and late promises.
|
|
82
|
+
void Promise.resolve(value).then(
|
|
83
|
+
(answer) => {
|
|
84
|
+
if (accepted && !done) finish(answer);
|
|
85
|
+
},
|
|
86
|
+
() => {
|
|
87
|
+
if (accepted && !done) finish();
|
|
88
|
+
},
|
|
89
|
+
);
|
|
90
|
+
return accepted;
|
|
91
|
+
},
|
|
92
|
+
});
|
|
93
|
+
// Event listeners can synchronously replace the session or mutate the model.
|
|
94
|
+
if (!current()) finish();
|
|
95
|
+
} catch {
|
|
96
|
+
finish();
|
|
97
|
+
} finally {
|
|
98
|
+
open = false;
|
|
99
|
+
}
|
|
100
|
+
if (!offered) finish();
|
|
101
|
+
});
|
|
102
|
+
if (!current()) return undefined;
|
|
103
|
+
const reset = selectReset(result, provider, modelId, modelName, startedAt);
|
|
104
|
+
return current() ? reset : undefined;
|
|
105
|
+
} catch {
|
|
106
|
+
// Neither protocol failures nor stale context getters may escape into recovery.
|
|
107
|
+
return undefined;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// Read only known own data properties. Reject accessors without running them, and
|
|
112
|
+
// detach nested records and array entries before validation or deadline selection.
|
|
113
|
+
// Do not enumerate unknown fields or use provider-controlled array iterators.
|
|
114
|
+
function dataProperty(value: object, key: string): unknown {
|
|
115
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
116
|
+
if (!descriptor) return undefined;
|
|
117
|
+
if (!("value" in descriptor)) throw new TypeError("Usage fields must be data properties");
|
|
118
|
+
return descriptor.value;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function snapshotFields(value: unknown, fields: readonly string[]): RecordValue {
|
|
122
|
+
if (!isRecord(value)) throw new TypeError("Usage records must be objects");
|
|
123
|
+
const snapshot: RecordValue = {};
|
|
124
|
+
for (const field of fields) snapshot[field] = dataProperty(value, field);
|
|
125
|
+
return snapshot;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function snapshotArray(value: unknown, project: (item: unknown) => unknown = (item) => item): unknown[] {
|
|
129
|
+
if (!Array.isArray(value)) throw new TypeError("Usage lists must be arrays");
|
|
130
|
+
const length = dataProperty(value, "length");
|
|
131
|
+
if (!isFiniteNumber(length) || !Number.isInteger(length) || length < 0 || length > 0xffff_ffff) {
|
|
132
|
+
throw new TypeError("Usage arrays must have a valid length");
|
|
133
|
+
}
|
|
134
|
+
const snapshot: unknown[] = [];
|
|
135
|
+
for (let index = 0; index < length; index++) snapshot.push(project(dataProperty(value, String(index))));
|
|
136
|
+
return snapshot;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function snapshotBucket(value: unknown): RecordValue {
|
|
140
|
+
const bucket = snapshotFields(value, [
|
|
141
|
+
"id",
|
|
142
|
+
"label",
|
|
143
|
+
"groupId",
|
|
144
|
+
"groupLabel",
|
|
145
|
+
"modelKeys",
|
|
146
|
+
"used",
|
|
147
|
+
"remaining",
|
|
148
|
+
"limit",
|
|
149
|
+
"unit",
|
|
150
|
+
"period",
|
|
151
|
+
"windowMinutes",
|
|
152
|
+
"resetsAt",
|
|
153
|
+
]);
|
|
154
|
+
if (bucket.modelKeys !== undefined) bucket.modelKeys = snapshotArray(bucket.modelKeys);
|
|
155
|
+
return bucket;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function snapshotResult(input: unknown): RecordValue {
|
|
159
|
+
const value = snapshotFields(input, ["status", "providerId", "source", "expiresAt", "report"]);
|
|
160
|
+
const report = snapshotFields(value.report, [
|
|
161
|
+
"providerId",
|
|
162
|
+
"providerName",
|
|
163
|
+
"capturedAt",
|
|
164
|
+
"source",
|
|
165
|
+
"semantics",
|
|
166
|
+
"accountLabel",
|
|
167
|
+
"buckets",
|
|
168
|
+
"metrics",
|
|
169
|
+
"notes",
|
|
170
|
+
]);
|
|
171
|
+
value.report = report;
|
|
172
|
+
report.semantics = snapshotFields(report.semantics, ["kind", "label"]);
|
|
173
|
+
report.buckets = snapshotArray(report.buckets, snapshotBucket);
|
|
174
|
+
report.metrics = snapshotArray(report.metrics, (metric) =>
|
|
175
|
+
snapshotFields(metric, ["id", "label", "value", "unit", "currency"]),
|
|
176
|
+
);
|
|
177
|
+
if (report.notes !== undefined) report.notes = snapshotArray(report.notes);
|
|
178
|
+
return value;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
function selectReset(
|
|
182
|
+
input: unknown,
|
|
183
|
+
provider: string,
|
|
184
|
+
modelId: string,
|
|
185
|
+
modelName: string,
|
|
186
|
+
startedAt: number,
|
|
187
|
+
): number | undefined {
|
|
188
|
+
const value = snapshotResult(input);
|
|
189
|
+
const now = Date.now();
|
|
190
|
+
if (
|
|
191
|
+
value.status !== "ready" ||
|
|
192
|
+
value.providerId !== provider ||
|
|
193
|
+
value.source !== "refresh" ||
|
|
194
|
+
!isTimestamp(value.expiresAt) ||
|
|
195
|
+
value.expiresAt <= now
|
|
196
|
+
) {
|
|
197
|
+
return undefined;
|
|
198
|
+
}
|
|
199
|
+
const report = value.report;
|
|
200
|
+
if (
|
|
201
|
+
!isRecord(report) ||
|
|
202
|
+
report.providerId !== provider ||
|
|
203
|
+
typeof report.providerName !== "string" ||
|
|
204
|
+
typeof report.source !== "string" ||
|
|
205
|
+
!isTimestamp(report.capturedAt) ||
|
|
206
|
+
report.capturedAt < startedAt ||
|
|
207
|
+
report.capturedAt > now ||
|
|
208
|
+
!isRecord(report.semantics) ||
|
|
209
|
+
typeof report.semantics.kind !== "string" ||
|
|
210
|
+
!["consumer-subscription", "api-key", "project"].includes(report.semantics.kind) ||
|
|
211
|
+
typeof report.semantics.label !== "string" ||
|
|
212
|
+
!optional(report.accountLabel, isString) ||
|
|
213
|
+
!optional(report.notes, isStrings) ||
|
|
214
|
+
!Array.isArray(report.buckets) ||
|
|
215
|
+
!Array.isArray(report.metrics) ||
|
|
216
|
+
![...report.metrics].every(isMetric)
|
|
217
|
+
) {
|
|
218
|
+
return undefined;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
const buckets: unknown[] = [...report.buckets];
|
|
222
|
+
if (!buckets.every(isBucket)) return undefined;
|
|
223
|
+
let latest: number | undefined;
|
|
224
|
+
const constraints = new Set<string>();
|
|
225
|
+
for (const bucket of buckets) {
|
|
226
|
+
// Repeated constraint identities leave their window relationship ambiguous.
|
|
227
|
+
if (constraints.has(bucket.id)) return undefined;
|
|
228
|
+
constraints.add(bucket.id);
|
|
229
|
+
// V1 has no base/all-model marker. Omitted/empty modelKeys cannot prove scope,
|
|
230
|
+
// even when a label, group, or opaque ID suggests a provider-wide allowance.
|
|
231
|
+
// Do not infer scope or window relationships from those presentation fields.
|
|
232
|
+
if (!bucket.modelKeys?.length) return undefined;
|
|
233
|
+
if (!bucket.modelKeys.includes(modelId) && !bucket.modelKeys.includes(modelName)) continue;
|
|
234
|
+
|
|
235
|
+
const { used, remaining, limit } = bucket;
|
|
236
|
+
// Zero/negative limits and negative usage do not prove meaningful quota bounds.
|
|
237
|
+
if ((used !== undefined && used < 0) || (limit !== undefined && limit <= 0)) return undefined;
|
|
238
|
+
const byRemaining = remaining === undefined ? undefined : remaining <= 0;
|
|
239
|
+
const byUsage = used === undefined || limit === undefined ? undefined : used >= limit;
|
|
240
|
+
if (byRemaining === undefined && byUsage === undefined) return undefined;
|
|
241
|
+
if (byRemaining !== undefined && byUsage !== undefined && byRemaining !== byUsage) return undefined;
|
|
242
|
+
if (!(byRemaining ?? byUsage)) continue;
|
|
243
|
+
if (!isTimestamp(bucket.resetsAt) || bucket.resetsAt <= now) return undefined;
|
|
244
|
+
// Treat confirmed constraints separately: availability requires all to reset.
|
|
245
|
+
// This does not add measurements or infer a request-specific retry guarantee.
|
|
246
|
+
latest = Math.max(latest ?? bucket.resetsAt, bucket.resetsAt);
|
|
247
|
+
}
|
|
248
|
+
const completedAt = Date.now();
|
|
249
|
+
return isTimestamp(latest) &&
|
|
250
|
+
latest > completedAt &&
|
|
251
|
+
value.expiresAt > completedAt &&
|
|
252
|
+
report.capturedAt <= completedAt
|
|
253
|
+
? latest
|
|
254
|
+
: undefined;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
function isBucket(value: unknown): value is Bucket {
|
|
258
|
+
return (
|
|
259
|
+
isRecord(value) &&
|
|
260
|
+
typeof value.id === "string" &&
|
|
261
|
+
typeof value.label === "string" &&
|
|
262
|
+
typeof value.unit === "string" &&
|
|
263
|
+
UNITS.has(value.unit) &&
|
|
264
|
+
optional(value.groupId, isString) &&
|
|
265
|
+
optional(value.groupLabel, isString) &&
|
|
266
|
+
optional(value.modelKeys, isStrings) &&
|
|
267
|
+
optional(value.used, isFiniteNumber) &&
|
|
268
|
+
optional(value.remaining, isFiniteNumber) &&
|
|
269
|
+
optional(value.limit, isFiniteNumber) &&
|
|
270
|
+
optional(value.period, isString) &&
|
|
271
|
+
optional(value.windowMinutes, (number) => isFiniteNumber(number) && number > 0) &&
|
|
272
|
+
optional(value.resetsAt, isTimestamp)
|
|
273
|
+
);
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
function isMetric(value: unknown): boolean {
|
|
277
|
+
return (
|
|
278
|
+
isRecord(value) &&
|
|
279
|
+
typeof value.id === "string" &&
|
|
280
|
+
typeof value.label === "string" &&
|
|
281
|
+
(typeof value.value === "string" || isFiniteNumber(value.value)) &&
|
|
282
|
+
optional(value.unit, (unit) => typeof unit === "string" && UNITS.has(unit)) &&
|
|
283
|
+
optional(value.currency, isString)
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
function isRecord(value: unknown): value is RecordValue {
|
|
288
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
function isString(value: unknown): value is string {
|
|
292
|
+
return typeof value === "string";
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
function isStrings(value: unknown): value is string[] {
|
|
296
|
+
return Array.isArray(value) && [...value].every(isString);
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
function isFiniteNumber(value: unknown): value is number {
|
|
300
|
+
return typeof value === "number" && Number.isFinite(value);
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
function isTimestamp(value: unknown): value is number {
|
|
304
|
+
return isFiniteNumber(value) && Number.isSafeInteger(value) && value >= 0 && value <= MAX_TIMESTAMP_MS;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
function optional(value: unknown, validate: (value: unknown) => boolean): boolean {
|
|
308
|
+
return value === undefined || validate(value);
|
|
309
|
+
}
|
package/src/wait.ts
CHANGED
|
@@ -1,6 +1,13 @@
|
|
|
1
|
+
export interface UsageLimitScope {
|
|
2
|
+
provider: string;
|
|
3
|
+
model: string;
|
|
4
|
+
api: string;
|
|
5
|
+
}
|
|
6
|
+
|
|
1
7
|
export interface GoalWait {
|
|
2
8
|
reason: string;
|
|
3
9
|
resumeAt?: number;
|
|
10
|
+
usageLimit?: UsageLimitScope;
|
|
4
11
|
}
|
|
5
12
|
|
|
6
13
|
export const MAX_GOAL_WAIT_REASON_LENGTH = 1_000;
|
|
@@ -31,6 +38,19 @@ export function normalizeGoalWait(value: unknown): GoalWait | undefined {
|
|
|
31
38
|
if (!isRecord(value)) return undefined;
|
|
32
39
|
const reason = typeof value.reason === "string" ? value.reason.trim() : "";
|
|
33
40
|
if (!reason || reason.length > MAX_GOAL_WAIT_REASON_LENGTH) return undefined;
|
|
41
|
+
let usageLimit: UsageLimitScope | undefined;
|
|
42
|
+
if (Object.hasOwn(value, "usageLimit")) {
|
|
43
|
+
const scope = value.usageLimit;
|
|
44
|
+
if (
|
|
45
|
+
!isRecord(scope) ||
|
|
46
|
+
typeof scope.provider !== "string" ||
|
|
47
|
+
typeof scope.model !== "string" ||
|
|
48
|
+
typeof scope.api !== "string" ||
|
|
49
|
+
!Object.hasOwn(value, "resumeAt")
|
|
50
|
+
)
|
|
51
|
+
return undefined;
|
|
52
|
+
usageLimit = { provider: scope.provider, model: scope.model, api: scope.api };
|
|
53
|
+
}
|
|
34
54
|
if (!Object.hasOwn(value, "resumeAt")) return { reason };
|
|
35
55
|
if (
|
|
36
56
|
typeof value.resumeAt !== "number" ||
|
|
@@ -40,7 +60,7 @@ export function normalizeGoalWait(value: unknown): GoalWait | undefined {
|
|
|
40
60
|
) {
|
|
41
61
|
return undefined;
|
|
42
62
|
}
|
|
43
|
-
return { reason, resumeAt: value.resumeAt };
|
|
63
|
+
return { reason, resumeAt: value.resumeAt, ...(usageLimit ? { usageLimit } : {}) };
|
|
44
64
|
}
|
|
45
65
|
|
|
46
66
|
export class GoalWaitTimer {
|