@deliverd/sdk 0.37.0 → 0.39.0
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/README.md +34 -0
- package/dist/adapters/index.d.ts +6 -0
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +3 -0
- package/dist/adapters/muse-spark.d.ts +6 -0
- package/dist/adapters/muse-spark.d.ts.map +1 -1
- package/dist/adapters/muse-spark.js +7 -2
- package/dist/adapters/openrouter.d.ts +277 -0
- package/dist/adapters/openrouter.d.ts.map +1 -0
- package/dist/adapters/openrouter.js +439 -0
- package/dist/adapters/perplexity.d.ts +99 -0
- package/dist/adapters/perplexity.d.ts.map +1 -0
- package/dist/adapters/perplexity.js +150 -0
- package/dist/adapters/shared.d.ts +1 -1
- package/dist/governance.d.ts +6 -1
- package/dist/governance.d.ts.map +1 -1
- package/dist/governance.js +8 -0
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +3101 -0
- package/dist/types.d.ts +33 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/adapters/index.ts +42 -0
- package/src/adapters/muse-spark.ts +9 -3
- package/src/adapters/openrouter.ts +678 -0
- package/src/adapters/perplexity.ts +236 -0
- package/src/adapters/shared.ts +1 -1
- package/src/governance.ts +10 -0
- package/src/released.ts +3103 -0
- package/src/types.ts +36 -0
|
@@ -0,0 +1,678 @@
|
|
|
1
|
+
import { DeliverdTimeoutError } from "../errors.js";
|
|
2
|
+
import type { Duration } from "../duration.js";
|
|
3
|
+
import type { ApprovalRisk, Decision, RegisterAiSystemInput, UsePolicy, UsePolicyData, UsePolicyDeploymentClass } from "../types.js";
|
|
4
|
+
import { askAboutCall, type Approver, type ToolApprovalOptions } from "./shared.js";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* OpenRouter's Agent SDK (`@openrouter/agent`): a person approves the tool
|
|
8
|
+
* calls you mark `requireApproval`, through Deliverd.
|
|
9
|
+
*
|
|
10
|
+
* OpenRouter pauses a run when a tool marked `requireApproval` is called and
|
|
11
|
+
* leaves who decides, and where, to you. Two ways to hand that to Deliverd:
|
|
12
|
+
*
|
|
13
|
+
* In the run, with the `PermissionRequest` hook, which fires just before the
|
|
14
|
+
* SDK would pause. The run waits for the person and goes on by itself; a no
|
|
15
|
+
* reaches the model with the person's reason.
|
|
16
|
+
*
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { OpenRouter } from "@openrouter/agent";
|
|
19
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
20
|
+
* import { deliverdPermissionRequest } from "@deliverd/sdk/adapters";
|
|
21
|
+
*
|
|
22
|
+
* const result = openrouter.callModel({
|
|
23
|
+
* model: "anthropic/claude-sonnet-4.5",
|
|
24
|
+
* input: "Refund order 1042",
|
|
25
|
+
* tools: [refundTool], // tool({ ..., requireApproval: true })
|
|
26
|
+
* hooks: { PermissionRequest: [deliverdPermissionRequest({ deliverd: new Deliverd(), approvers: ["finance"] })] },
|
|
27
|
+
* });
|
|
28
|
+
* console.log(await result.getText());
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* Or across a pause, for a wait longer than a process should hold open: let
|
|
32
|
+
* the run pause as OpenRouter does (with a `state` accessor), then
|
|
33
|
+
* `resolveOpenRouterApprovals(result, options)` asks about each pending call
|
|
34
|
+
* and returns the `approveToolCalls` and `rejectToolCalls` to resume with.
|
|
35
|
+
* Each call is keyed by the conversation and call id, so asking again after a
|
|
36
|
+
* restart finds the same request rather than filing a second one. OpenRouter
|
|
37
|
+
* tells the model only "Rejected by user" on this path; the hook passes the
|
|
38
|
+
* person's own reason.
|
|
39
|
+
*
|
|
40
|
+
* Shapes follow `@openrouter/agent` 1.2.1's type definitions: the
|
|
41
|
+
* `PermissionRequest` entry of `BuiltInHookDefinitions` (`HookEntry`,
|
|
42
|
+
* `PermissionRequestPayload` `{ toolName, toolInput, riskLevel }`,
|
|
43
|
+
* `PermissionRequestResult` `{ decision: "allow" | "deny" | "ask_user",
|
|
44
|
+
* reason }`, `LifecycleHookContext` `{ signal, hookName, sessionId }`) in
|
|
45
|
+
* `esm/lib/hooks-types.d.ts` and `hooks-schemas.d.ts`; `ModelResult`'s
|
|
46
|
+
* `getPendingToolCalls()` and `getState()` in `esm/lib/model-result.d.ts`;
|
|
47
|
+
* and `ParsedToolCall` `{ id, name, arguments }` and `ConversationState`'s
|
|
48
|
+
* `id` and `status` in `esm/lib/tool-types.d.ts`.
|
|
49
|
+
*/
|
|
50
|
+
|
|
51
|
+
/** The `PermissionRequest` hook payload. */
|
|
52
|
+
export interface OpenRouterPermissionPayload {
|
|
53
|
+
toolName: string;
|
|
54
|
+
toolInput: Record<string, unknown>;
|
|
55
|
+
riskLevel?: "low" | "medium" | "high";
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** What a `PermissionRequest` handler returns. */
|
|
59
|
+
export interface OpenRouterPermissionResult {
|
|
60
|
+
decision: "allow" | "deny" | "ask_user";
|
|
61
|
+
reason?: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The hook context OpenRouter passes every handler. */
|
|
65
|
+
export interface OpenRouterHookContext {
|
|
66
|
+
signal?: AbortSignal;
|
|
67
|
+
sessionId?: string;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** A `HookEntry` for `hooks.PermissionRequest`. */
|
|
71
|
+
export interface OpenRouterPermissionHook {
|
|
72
|
+
handler: (payload: OpenRouterPermissionPayload, context: OpenRouterHookContext) => Promise<OpenRouterPermissionResult>;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* A `PermissionRequest` hook entry: each call OpenRouter would pause for is
|
|
77
|
+
* decided by a person in Deliverd, and the run carries on.
|
|
78
|
+
*
|
|
79
|
+
* A call `when` does not select is allowed, as with the other adapters.
|
|
80
|
+
* OpenRouter's payload carries no call id, so a call is keyed by the session
|
|
81
|
+
* (or, when the run names none, this hook), the tool, its input and how many
|
|
82
|
+
* times that same call has come up: the same call asked again in one run gets
|
|
83
|
+
* a request of its own, and another run never reuses this one's yes.
|
|
84
|
+
*/
|
|
85
|
+
export function deliverdPermissionRequest(options: ToolApprovalOptions): OpenRouterPermissionHook {
|
|
86
|
+
const seen = new Map<string, number>();
|
|
87
|
+
// OpenRouter leaves the session id empty unless the run names one; a key
|
|
88
|
+
// without it would let one run reuse another's yes for the same input.
|
|
89
|
+
const instance = `run_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
|
|
90
|
+
return {
|
|
91
|
+
async handler(payload, context) {
|
|
92
|
+
const toolName = payload.toolName || "a tool";
|
|
93
|
+
const input = payload.toolInput ?? {};
|
|
94
|
+
if (options.when && !(await options.when(toolName, input))) return { decision: "allow" };
|
|
95
|
+
const base = `openrouter:${context?.sessionId || instance}:${toolName}:${fingerprint(input)}`;
|
|
96
|
+
const occurrence = (seen.get(base) ?? 0) + 1;
|
|
97
|
+
seen.set(base, occurrence);
|
|
98
|
+
const outcome = await askAboutCall(
|
|
99
|
+
toolName,
|
|
100
|
+
input,
|
|
101
|
+
occurrence === 1 ? base : `${base}:${occurrence}`,
|
|
102
|
+
withRisk(options, payload.riskLevel),
|
|
103
|
+
context?.signal
|
|
104
|
+
);
|
|
105
|
+
return outcome.allowed ? { decision: "allow" } : { decision: "deny", reason: outcome.reason };
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** The part of a `ParsedToolCall` this adapter reads. */
|
|
111
|
+
export interface OpenRouterPendingCall {
|
|
112
|
+
id: string;
|
|
113
|
+
name: string;
|
|
114
|
+
arguments: unknown;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** The part of a `ModelResult` this adapter reads. */
|
|
118
|
+
export interface OpenRouterPausedResult {
|
|
119
|
+
getPendingToolCalls(): Promise<OpenRouterPendingCall[]>;
|
|
120
|
+
getState(): Promise<{ id: string; status?: string }>;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** What to resume a paused conversation with: pass both to `callModel` with the same `state`. */
|
|
124
|
+
export interface OpenRouterResume {
|
|
125
|
+
approveToolCalls: string[];
|
|
126
|
+
rejectToolCalls: string[];
|
|
127
|
+
/** Each refused call's reason, by call id, for your own log. OpenRouter does not pass it on. */
|
|
128
|
+
reasons: Record<string, string>;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Ask about every call a paused run is waiting on, and return the decisions
|
|
133
|
+
* to resume it with. Calls `when` does not select are approved.
|
|
134
|
+
*/
|
|
135
|
+
export async function resolveOpenRouterApprovals(
|
|
136
|
+
result: OpenRouterPausedResult,
|
|
137
|
+
options: ToolApprovalOptions
|
|
138
|
+
): Promise<OpenRouterResume> {
|
|
139
|
+
const resume: OpenRouterResume = { approveToolCalls: [], rejectToolCalls: [], reasons: {} };
|
|
140
|
+
const pending = await result.getPendingToolCalls();
|
|
141
|
+
if (pending.length === 0) return resume;
|
|
142
|
+
const { id: conversationId } = await result.getState();
|
|
143
|
+
for (const call of pending) {
|
|
144
|
+
const toolName = String(call.name || "a tool");
|
|
145
|
+
const input = parseArguments(call.arguments);
|
|
146
|
+
if (options.when && !(await options.when(toolName, input))) {
|
|
147
|
+
resume.approveToolCalls.push(call.id);
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
const outcome = await askAboutCall(toolName, input, `openrouter:${conversationId}:${call.id}`, options);
|
|
151
|
+
if (outcome.allowed) {
|
|
152
|
+
resume.approveToolCalls.push(call.id);
|
|
153
|
+
} else {
|
|
154
|
+
resume.rejectToolCalls.push(call.id);
|
|
155
|
+
resume.reasons[call.id] = outcome.reason;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
return resume;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** OpenRouter's own reading of the risk, when the caller did not describe the call. */
|
|
162
|
+
function withRisk(options: ToolApprovalOptions, risk: OpenRouterPermissionPayload["riskLevel"]): ToolApprovalOptions {
|
|
163
|
+
if (options.describe || !risk) return options;
|
|
164
|
+
return {
|
|
165
|
+
...options,
|
|
166
|
+
describe: (toolName, input) => {
|
|
167
|
+
const rendered = safeJson(input);
|
|
168
|
+
return {
|
|
169
|
+
title: `Allow the agent to run ${toolName}`,
|
|
170
|
+
description: rendered ? `With this input:\n\n${rendered}` : undefined,
|
|
171
|
+
risk,
|
|
172
|
+
};
|
|
173
|
+
},
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function parseArguments(raw: unknown): unknown {
|
|
178
|
+
if (typeof raw !== "string") return raw ?? {};
|
|
179
|
+
try {
|
|
180
|
+
return JSON.parse(raw);
|
|
181
|
+
} catch {
|
|
182
|
+
return raw;
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function safeJson(input: unknown): string {
|
|
187
|
+
try {
|
|
188
|
+
const text = JSON.stringify(input, null, 2) ?? "";
|
|
189
|
+
return text.length > 3000 ? `${text.slice(0, 2999)}…` : text;
|
|
190
|
+
} catch {
|
|
191
|
+
return String(input);
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** A short, stable key for an input: FNV-1a over its JSON with sorted keys. */
|
|
196
|
+
function fingerprint(input: unknown): string {
|
|
197
|
+
const text = canonical(input);
|
|
198
|
+
let hash = 0x811c9dc5;
|
|
199
|
+
for (let i = 0; i < text.length; i++) {
|
|
200
|
+
hash ^= text.charCodeAt(i);
|
|
201
|
+
hash = Math.imul(hash, 0x01000193) >>> 0;
|
|
202
|
+
}
|
|
203
|
+
return hash.toString(16).padStart(8, "0");
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function canonical(value: unknown): string {
|
|
207
|
+
if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
|
|
208
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
|
|
209
|
+
const entries = Object.keys(value as Record<string, unknown>)
|
|
210
|
+
.sort()
|
|
211
|
+
.map((key) => `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`);
|
|
212
|
+
return `{${entries.join(",")}}`;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/* ── OpenRouter's own controls and activity ─────────────────────────────── */
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* OpenRouter's own controls, with a person's yes on every change, and the
|
|
219
|
+
* AI register kept to what OpenRouter actually routes.
|
|
220
|
+
*
|
|
221
|
+
* OpenRouter guardrails set what a key may spend, which models and providers
|
|
222
|
+
* it may reach, zero data retention and data regions. Anyone holding a
|
|
223
|
+
* management key can change them, and nothing records who agreed. These
|
|
224
|
+
* helpers run on your side, with your management key, which never reaches
|
|
225
|
+
* Deliverd:
|
|
226
|
+
*
|
|
227
|
+
* - `changeOpenRouterGuardrail` reads the guardrail, shows a person what would
|
|
228
|
+
* change, and applies it only on their yes.
|
|
229
|
+
* - `raiseOpenRouterKeyLimit` does the same for one key's credit limit.
|
|
230
|
+
* - `openRouterGuardrailForData` reads your AI use policy for the data a key
|
|
231
|
+
* will carry and says whether OpenRouter may carry it at all, and with which
|
|
232
|
+
* guardrail settings.
|
|
233
|
+
* - `openRouterModelsInUse` reads OpenRouter's activity (the last 30 days, by
|
|
234
|
+
* model) and `registerOpenRouterModels` adds the models nobody registered to
|
|
235
|
+
* the AI register, as found in use, for a person to triage.
|
|
236
|
+
*
|
|
237
|
+
* Shapes follow `@openrouter/sdk` 1.5.103's generated models: `Guardrail` and
|
|
238
|
+
* `UpdateGuardrailRequest` (snake_case on the wire, `GET`/`PATCH
|
|
239
|
+
* /guardrails/{id}`, answered as `{ data }`), `UpdateKeysRequestBody`
|
|
240
|
+
* (`limit`, `limit_reset`; `GET`/`PATCH /keys/{hash}`) and `ActivityItem`
|
|
241
|
+
* (`GET /activity`: `date`, `model`, `provider_name`, `requests`, `usage`).
|
|
242
|
+
*/
|
|
243
|
+
|
|
244
|
+
export interface OpenRouterAdmin {
|
|
245
|
+
/** A management key (OpenRouter → Settings → Management keys). It stays in your process. */
|
|
246
|
+
managementKey: string;
|
|
247
|
+
/** Default `https://openrouter.ai/api/v1`; `https://eu.openrouter.ai/api/v1` for EU in-region routing. */
|
|
248
|
+
baseUrl?: string;
|
|
249
|
+
fetch?: typeof fetch;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** The guardrail settings these helpers read and change, as OpenRouter names them in its SDK. */
|
|
253
|
+
export interface OpenRouterGuardrailSettings {
|
|
254
|
+
name?: string;
|
|
255
|
+
description?: string | null;
|
|
256
|
+
/** Spend limit in US dollars; null removes it. */
|
|
257
|
+
limitUsd?: number | null;
|
|
258
|
+
resetInterval?: "daily" | "weekly" | "monthly" | null;
|
|
259
|
+
allowedModels?: string[] | null;
|
|
260
|
+
ignoredModels?: string[] | null;
|
|
261
|
+
allowedProviders?: string[] | null;
|
|
262
|
+
ignoredProviders?: string[] | null;
|
|
263
|
+
/** Zero data retention, for every provider. */
|
|
264
|
+
enforceZdr?: boolean | null;
|
|
265
|
+
allowedDataRegions?: ("global" | "europe" | "us")[] | null;
|
|
266
|
+
enablePaidModelTraining?: boolean | null;
|
|
267
|
+
enableFreeModelTraining?: boolean | null;
|
|
268
|
+
enableFreeModelPublication?: boolean | null;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
export interface OpenRouterChangeOptions {
|
|
272
|
+
/** The client: `new Deliverd()`. */
|
|
273
|
+
deliverd: Approver;
|
|
274
|
+
openrouter: OpenRouterAdmin;
|
|
275
|
+
/** Who may decide. The organisation's admins when omitted. */
|
|
276
|
+
approvers?: string[];
|
|
277
|
+
/** Why the change is wanted, in a sentence the approver reads first. */
|
|
278
|
+
reason?: string;
|
|
279
|
+
/** How long the request stays open. Default one day: nobody is waiting on a run. */
|
|
280
|
+
expiresIn?: Duration;
|
|
281
|
+
timeout?: Duration;
|
|
282
|
+
flowId?: string;
|
|
283
|
+
metadata?: Record<string, unknown>;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** What happened to a change. */
|
|
287
|
+
export type OpenRouterChangeResult =
|
|
288
|
+
| { applied: true; decidedBy: string | null; approvalId: string; changes: string[] }
|
|
289
|
+
| { applied: false; reason: string; approvalId: string | null; changes: string[] };
|
|
290
|
+
|
|
291
|
+
const FIELDS: { key: keyof OpenRouterGuardrailSettings; wire: string; label: string }[] = [
|
|
292
|
+
{ key: "name", wire: "name", label: "Name" },
|
|
293
|
+
{ key: "description", wire: "description", label: "Description" },
|
|
294
|
+
{ key: "limitUsd", wire: "limit_usd", label: "Spend limit (USD)" },
|
|
295
|
+
{ key: "resetInterval", wire: "reset_interval", label: "Limit resets" },
|
|
296
|
+
{ key: "allowedModels", wire: "allowed_models", label: "Allowed models" },
|
|
297
|
+
{ key: "ignoredModels", wire: "ignored_models", label: "Blocked models" },
|
|
298
|
+
{ key: "allowedProviders", wire: "allowed_providers", label: "Allowed providers" },
|
|
299
|
+
{ key: "ignoredProviders", wire: "ignored_providers", label: "Blocked providers" },
|
|
300
|
+
{ key: "enforceZdr", wire: "enforce_zdr", label: "Zero data retention" },
|
|
301
|
+
{ key: "allowedDataRegions", wire: "allowed_data_regions", label: "Data regions" },
|
|
302
|
+
{ key: "enablePaidModelTraining", wire: "enable_paid_model_training", label: "Paid models may train on prompts" },
|
|
303
|
+
{ key: "enableFreeModelTraining", wire: "enable_free_model_training", label: "Free models may train on prompts" },
|
|
304
|
+
{ key: "enableFreeModelPublication", wire: "enable_free_model_publication", label: "Free models may publish prompts" },
|
|
305
|
+
];
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Change an OpenRouter guardrail only once a person says yes.
|
|
309
|
+
*
|
|
310
|
+
* The approver sees each setting that would change, before and after. A
|
|
311
|
+
* change that loosens anything (a higher or removed spend limit, zero data
|
|
312
|
+
* retention off, training on, more regions, models or providers) is asked as
|
|
313
|
+
* high risk. The same change to the same guardrail, asked again before it was
|
|
314
|
+
* applied, finds the same request; once the guardrail has changed, a new ask
|
|
315
|
+
* is a new request.
|
|
316
|
+
*/
|
|
317
|
+
export async function changeOpenRouterGuardrail(
|
|
318
|
+
guardrailId: string,
|
|
319
|
+
change: OpenRouterGuardrailSettings,
|
|
320
|
+
options: OpenRouterChangeOptions
|
|
321
|
+
): Promise<OpenRouterChangeResult> {
|
|
322
|
+
const path = `/guardrails/${encodeURIComponent(guardrailId)}`;
|
|
323
|
+
const current = await openRouterRequest<Record<string, unknown>>(options.openrouter, "GET", path);
|
|
324
|
+
const body: Record<string, unknown> = {};
|
|
325
|
+
const lines: string[] = [];
|
|
326
|
+
let loosens = false;
|
|
327
|
+
for (const { key, wire, label } of FIELDS) {
|
|
328
|
+
if (!(key in change)) continue;
|
|
329
|
+
const next = change[key] ?? null;
|
|
330
|
+
const before = current[wire] ?? null;
|
|
331
|
+
if (same(before, next)) continue;
|
|
332
|
+
body[wire] = next;
|
|
333
|
+
lines.push(`${label}: ${show(before)} → ${show(next)}`);
|
|
334
|
+
if (loosening(key, before, next)) loosens = true;
|
|
335
|
+
}
|
|
336
|
+
if (lines.length === 0) {
|
|
337
|
+
return { applied: false, reason: "The guardrail already has these settings, so nothing was asked or changed.", approvalId: null, changes: [] };
|
|
338
|
+
}
|
|
339
|
+
const name = typeof current.name === "string" ? current.name : guardrailId;
|
|
340
|
+
const outcome = await ask(options, {
|
|
341
|
+
title: `Change the OpenRouter guardrail “${name}”`,
|
|
342
|
+
description: [options.reason, lines.map((line) => `- ${line}`).join("\n")].filter(Boolean).join("\n\n"),
|
|
343
|
+
risk: loosens ? "high" : "medium",
|
|
344
|
+
externalId: `openrouter-guardrail:${guardrailId}:${String(current.updated_at ?? current.created_at ?? "")}:${digestOf(body)}`,
|
|
345
|
+
input: body,
|
|
346
|
+
metadata: { openrouterGuardrailId: guardrailId },
|
|
347
|
+
});
|
|
348
|
+
if (!outcome.allowed) return { applied: false, reason: outcome.reason, approvalId: outcome.approvalId, changes: lines };
|
|
349
|
+
await openRouterRequest(options.openrouter, "PATCH", path, body);
|
|
350
|
+
return { applied: true, decidedBy: outcome.decidedBy, approvalId: outcome.approvalId, changes: lines };
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* Raise (or change, or remove) one OpenRouter key's credit limit only once a
|
|
355
|
+
* person says yes. The approver sees what the key has spent against its
|
|
356
|
+
* current limit. Removing a limit, or more than doubling it, is high risk.
|
|
357
|
+
*/
|
|
358
|
+
export async function raiseOpenRouterKeyLimit(
|
|
359
|
+
keyHash: string,
|
|
360
|
+
next: { limit: number | null; limitReset?: "daily" | "weekly" | "monthly" | null },
|
|
361
|
+
options: OpenRouterChangeOptions
|
|
362
|
+
): Promise<OpenRouterChangeResult> {
|
|
363
|
+
const path = `/keys/${encodeURIComponent(keyHash)}`;
|
|
364
|
+
const key = await openRouterRequest<Record<string, unknown>>(options.openrouter, "GET", path);
|
|
365
|
+
const before = typeof key.limit === "number" ? key.limit : null;
|
|
366
|
+
const body: Record<string, unknown> = { limit: next.limit };
|
|
367
|
+
if ("limitReset" in next) body.limit_reset = next.limitReset ?? null;
|
|
368
|
+
const lines = [`Credit limit (USD): ${show(before)} → ${show(next.limit)}`];
|
|
369
|
+
if ("limitReset" in next && !same(key.limit_reset ?? null, next.limitReset ?? null)) {
|
|
370
|
+
lines.push(`Limit resets: ${show(key.limit_reset ?? null)} → ${show(next.limitReset ?? null)}`);
|
|
371
|
+
}
|
|
372
|
+
if (same(before, next.limit) && lines.length === 1) {
|
|
373
|
+
return { applied: false, reason: "The key already has this limit, so nothing was asked or changed.", approvalId: null, changes: [] };
|
|
374
|
+
}
|
|
375
|
+
const spent = typeof key.usage === "number" ? `It has spent $${key.usage.toFixed(2)} so far` : null;
|
|
376
|
+
const monthly = typeof key.usage_monthly === "number" ? `, $${key.usage_monthly.toFixed(2)} this month` : "";
|
|
377
|
+
const label = typeof key.name === "string" && key.name ? key.name : String(key.label ?? keyHash);
|
|
378
|
+
const outcome = await ask(options, {
|
|
379
|
+
title: next.limit === null ? `Remove the spend limit on OpenRouter key “${label}”` : `Set OpenRouter key “${label}” to a $${next.limit} limit`,
|
|
380
|
+
description: [options.reason, spent ? `${spent}${monthly}.` : null, lines.map((line) => `- ${line}`).join("\n")].filter(Boolean).join("\n\n"),
|
|
381
|
+
risk: next.limit === null || (before !== null && next.limit > before * 2) ? "high" : "medium",
|
|
382
|
+
externalId: `openrouter-key:${keyHash}:${String(key.updated_at ?? key.created_at ?? "")}:${digestOf(body)}`,
|
|
383
|
+
input: body,
|
|
384
|
+
metadata: { openrouterKeyHash: keyHash },
|
|
385
|
+
});
|
|
386
|
+
if (!outcome.allowed) return { applied: false, reason: outcome.reason, approvalId: outcome.approvalId, changes: lines };
|
|
387
|
+
await openRouterRequest(options.openrouter, "PATCH", path, body);
|
|
388
|
+
return { applied: true, decidedBy: outcome.decidedBy, approvalId: outcome.approvalId, changes: lines };
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** What the AI use policy says about sending this data through OpenRouter. */
|
|
392
|
+
export interface OpenRouterPolicyReading {
|
|
393
|
+
/** False when the policy keeps some of the data to a private deployment, or out of AI tools altogether. */
|
|
394
|
+
allowed: boolean;
|
|
395
|
+
/** The least-controlled kind of tool the policy accepts for all of the data. */
|
|
396
|
+
deploymentClass: UsePolicyDeploymentClass | null;
|
|
397
|
+
/** Guardrail settings that make OpenRouter that kind of tool, as far as settings can. Empty when nothing is needed. */
|
|
398
|
+
guardrail: OpenRouterGuardrailSettings;
|
|
399
|
+
/** Conditions the policy attaches, which still apply per use: a person asked, or a current DPIA. */
|
|
400
|
+
conditions: string[];
|
|
401
|
+
/** In a sentence or two, for a log or the approver. */
|
|
402
|
+
explanation: string;
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
const CLASS_ORDER: UsePolicyDeploymentClass[] = ["consumer", "enterprise", "private"];
|
|
406
|
+
|
|
407
|
+
/**
|
|
408
|
+
* Read the AI use policy for the data a key will carry.
|
|
409
|
+
*
|
|
410
|
+
* OpenRouter on its defaults is treated as a consumer tool. With zero data
|
|
411
|
+
* retention enforced and training and publication off, under your own
|
|
412
|
+
* agreement with OpenRouter, it is treated as an enterprise tenant. It is
|
|
413
|
+
* never a private deployment. Pass the policy from
|
|
414
|
+
* `deliverd.governance.aiUsePolicy()`.
|
|
415
|
+
*/
|
|
416
|
+
export function openRouterGuardrailForData(
|
|
417
|
+
policy: UsePolicy,
|
|
418
|
+
data: UsePolicyData[],
|
|
419
|
+
options: { region?: "europe" | "us" } = {}
|
|
420
|
+
): OpenRouterPolicyReading {
|
|
421
|
+
let needed = 0;
|
|
422
|
+
const conditions: string[] = [];
|
|
423
|
+
for (const kind of data.length ? data : (["internal"] as UsePolicyData[])) {
|
|
424
|
+
const row = policy.grid[kind];
|
|
425
|
+
const first = CLASS_ORDER.findIndex((cls) => row?.[cls] && row[cls].rule !== "no");
|
|
426
|
+
if (first === -1) {
|
|
427
|
+
return {
|
|
428
|
+
allowed: false,
|
|
429
|
+
deploymentClass: null,
|
|
430
|
+
guardrail: {},
|
|
431
|
+
conditions: [],
|
|
432
|
+
explanation: `The AI use policy says ${labelOf(kind)} goes into no AI tool, so it may not go through OpenRouter.`,
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
needed = Math.max(needed, first);
|
|
436
|
+
}
|
|
437
|
+
const cls = CLASS_ORDER[needed]!;
|
|
438
|
+
for (const kind of data) {
|
|
439
|
+
const cell = policy.grid[kind]?.[cls];
|
|
440
|
+
if (cell?.rule === "conditional" && cell.condition) conditions.push(`${labelOf(kind)}: ${cell.condition}`);
|
|
441
|
+
}
|
|
442
|
+
if (cls === "private") {
|
|
443
|
+
return {
|
|
444
|
+
allowed: false,
|
|
445
|
+
deploymentClass: cls,
|
|
446
|
+
guardrail: {},
|
|
447
|
+
conditions,
|
|
448
|
+
explanation: "The AI use policy keeps this data to a private deployment (your own cloud and region). OpenRouter is a hosted router, so it may not carry it.",
|
|
449
|
+
};
|
|
450
|
+
}
|
|
451
|
+
const guardrail: OpenRouterGuardrailSettings =
|
|
452
|
+
cls === "enterprise"
|
|
453
|
+
? { enforceZdr: true, enablePaidModelTraining: false, enableFreeModelTraining: false, enableFreeModelPublication: false }
|
|
454
|
+
: {};
|
|
455
|
+
if (options.region) guardrail.allowedDataRegions = [options.region];
|
|
456
|
+
return {
|
|
457
|
+
allowed: true,
|
|
458
|
+
deploymentClass: cls,
|
|
459
|
+
guardrail,
|
|
460
|
+
conditions,
|
|
461
|
+
explanation:
|
|
462
|
+
cls === "enterprise"
|
|
463
|
+
? "The AI use policy needs an enterprise tenant for this data. Enforce zero data retention and turn training and publication off, and make sure your agreement with OpenRouter covers it."
|
|
464
|
+
: "The AI use policy lets this data go into consumer tools, so no guardrail setting is needed for it.",
|
|
465
|
+
};
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/** One model OpenRouter routed to, from its activity. */
|
|
469
|
+
export interface OpenRouterModelUse {
|
|
470
|
+
model: string;
|
|
471
|
+
providers: string[];
|
|
472
|
+
requests: number;
|
|
473
|
+
/** US dollars. */
|
|
474
|
+
usage: number;
|
|
475
|
+
firstSeen: string;
|
|
476
|
+
lastSeen: string;
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
/** The models a management key's organisation used through OpenRouter, from its activity (the last 30 days), most requests first. */
|
|
480
|
+
export async function openRouterModelsInUse(openrouter: OpenRouterAdmin): Promise<OpenRouterModelUse[]> {
|
|
481
|
+
const { data } = await openRouterRequest<{ data?: Record<string, unknown>[] }>(openrouter, "GET", "/activity", undefined, true);
|
|
482
|
+
const byModel = new Map<string, OpenRouterModelUse>();
|
|
483
|
+
for (const row of data ?? []) {
|
|
484
|
+
const model = typeof row.model === "string" ? row.model : null;
|
|
485
|
+
if (!model) continue;
|
|
486
|
+
const date = typeof row.date === "string" ? row.date : "";
|
|
487
|
+
const entry = byModel.get(model) ?? { model, providers: [], requests: 0, usage: 0, firstSeen: date, lastSeen: date };
|
|
488
|
+
const provider = typeof row.provider_name === "string" ? row.provider_name : null;
|
|
489
|
+
if (provider && !entry.providers.includes(provider)) entry.providers.push(provider);
|
|
490
|
+
entry.requests += typeof row.requests === "number" ? row.requests : 0;
|
|
491
|
+
entry.usage += typeof row.usage === "number" ? row.usage : 0;
|
|
492
|
+
if (date && (!entry.firstSeen || date < entry.firstSeen)) entry.firstSeen = date;
|
|
493
|
+
if (date && date > entry.lastSeen) entry.lastSeen = date;
|
|
494
|
+
byModel.set(model, entry);
|
|
495
|
+
}
|
|
496
|
+
return [...byModel.values()].sort((a, b) => b.requests - a.requests);
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/** The part of the Deliverd client this needs: `deliverd.governance.aiSystems`. */
|
|
500
|
+
export interface RegisterClient {
|
|
501
|
+
governance: {
|
|
502
|
+
aiSystems: {
|
|
503
|
+
list(input?: { status?: "active" | "retired" }): Promise<{ id: string; model: string | null; name: string }[]>;
|
|
504
|
+
register(input: RegisterAiSystemInput): Promise<{ id: string; name: string }>;
|
|
505
|
+
};
|
|
506
|
+
};
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
/**
|
|
510
|
+
* Add each model OpenRouter routed to, and nobody registered, to the AI
|
|
511
|
+
* register as found in use (`entryType: "discovered"`, supplier OpenRouter),
|
|
512
|
+
* for a person to triage. A model already on a record, active or retired, is
|
|
513
|
+
* left alone. Returns what it added and what it skipped.
|
|
514
|
+
*/
|
|
515
|
+
export async function registerOpenRouterModels(options: {
|
|
516
|
+
deliverd: RegisterClient;
|
|
517
|
+
openrouter: OpenRouterAdmin;
|
|
518
|
+
/** Only models with at least this many requests. Default 1. */
|
|
519
|
+
minRequests?: number;
|
|
520
|
+
/** What to put on each new record, on top of what is found. */
|
|
521
|
+
defaults?: Partial<RegisterAiSystemInput>;
|
|
522
|
+
}): Promise<{ registered: { id: string; model: string }[]; skipped: string[] }> {
|
|
523
|
+
const [models, records] = await Promise.all([openRouterModelsInUse(options.openrouter), options.deliverd.governance.aiSystems.list()]);
|
|
524
|
+
const known = new Set(records.map((record) => record.model).filter((model): model is string => Boolean(model)));
|
|
525
|
+
const registered: { id: string; model: string }[] = [];
|
|
526
|
+
const skipped: string[] = [];
|
|
527
|
+
for (const use of models) {
|
|
528
|
+
if (known.has(use.model) || use.requests < (options.minRequests ?? 1)) {
|
|
529
|
+
skipped.push(use.model);
|
|
530
|
+
continue;
|
|
531
|
+
}
|
|
532
|
+
const record = await options.deliverd.governance.aiSystems.register({
|
|
533
|
+
name: `${use.model} via OpenRouter`,
|
|
534
|
+
provider: use.providers.join(", ") || null,
|
|
535
|
+
model: use.model,
|
|
536
|
+
supplier: "OpenRouter",
|
|
537
|
+
buildOrBuy: "buy",
|
|
538
|
+
entryType: "discovered",
|
|
539
|
+
purpose: `Found in OpenRouter activity: ${use.requests} request${use.requests === 1 ? "" : "s"} between ${use.firstSeen.slice(0, 10)} and ${use.lastSeen.slice(0, 10)}. Who uses it, and for what, is for a person to fill in.`,
|
|
540
|
+
...options.defaults,
|
|
541
|
+
});
|
|
542
|
+
known.add(use.model);
|
|
543
|
+
registered.push({ id: record.id, model: use.model });
|
|
544
|
+
}
|
|
545
|
+
return { registered, skipped };
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
/* ── Plumbing ─────────────────────────────────────────────────────────── */
|
|
549
|
+
|
|
550
|
+
async function openRouterRequest<T>(
|
|
551
|
+
admin: OpenRouterAdmin,
|
|
552
|
+
method: "GET" | "PATCH",
|
|
553
|
+
path: string,
|
|
554
|
+
body?: unknown,
|
|
555
|
+
whole = false
|
|
556
|
+
): Promise<T> {
|
|
557
|
+
const doFetch = admin.fetch ?? fetch;
|
|
558
|
+
const base = (admin.baseUrl ?? "https://openrouter.ai/api/v1").replace(/\/+$/, "");
|
|
559
|
+
const response = await doFetch(`${base}${path}`, {
|
|
560
|
+
method,
|
|
561
|
+
headers: {
|
|
562
|
+
authorization: `Bearer ${admin.managementKey}`,
|
|
563
|
+
...(body === undefined ? {} : { "content-type": "application/json" }),
|
|
564
|
+
},
|
|
565
|
+
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
566
|
+
});
|
|
567
|
+
const text = await response.text();
|
|
568
|
+
if (!response.ok) {
|
|
569
|
+
let message = text.slice(0, 300);
|
|
570
|
+
try {
|
|
571
|
+
const parsed = JSON.parse(text) as { error?: { message?: string } };
|
|
572
|
+
if (parsed.error?.message) message = parsed.error.message;
|
|
573
|
+
} catch {
|
|
574
|
+
/* keep the text */
|
|
575
|
+
}
|
|
576
|
+
throw new Error(`OpenRouter ${method} ${path} failed (${response.status}): ${message}`);
|
|
577
|
+
}
|
|
578
|
+
const json = text ? (JSON.parse(text) as Record<string, unknown>) : {};
|
|
579
|
+
return (whole ? json : (json.data ?? json)) as T;
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
type Asked = { allowed: true; decidedBy: string | null; approvalId: string } | { allowed: false; reason: string; approvalId: string | null };
|
|
583
|
+
|
|
584
|
+
async function ask(
|
|
585
|
+
options: OpenRouterChangeOptions,
|
|
586
|
+
request: { title: string; description: string; risk: ApprovalRisk; externalId: string; input: Record<string, unknown>; metadata: Record<string, unknown> }
|
|
587
|
+
): Promise<Asked> {
|
|
588
|
+
let decision: Decision;
|
|
589
|
+
try {
|
|
590
|
+
decision = await options.deliverd.approve({
|
|
591
|
+
title: request.title,
|
|
592
|
+
description: request.description,
|
|
593
|
+
risk: request.risk,
|
|
594
|
+
approvers: options.approvers,
|
|
595
|
+
externalId: request.externalId,
|
|
596
|
+
flowId: options.flowId,
|
|
597
|
+
input: request.input,
|
|
598
|
+
metadata: { ...options.metadata, ...request.metadata, source: "openrouter" },
|
|
599
|
+
expiresIn: options.expiresIn ?? "1d",
|
|
600
|
+
timeout: options.timeout,
|
|
601
|
+
});
|
|
602
|
+
} catch (err) {
|
|
603
|
+
if (err instanceof DeliverdTimeoutError) {
|
|
604
|
+
return { allowed: false, reason: "Nobody decided in time, so nothing was changed.", approvalId: null };
|
|
605
|
+
}
|
|
606
|
+
throw err;
|
|
607
|
+
}
|
|
608
|
+
if (decision.approved) return { allowed: true, decidedBy: decision.decidedBy, approvalId: decision.id };
|
|
609
|
+
const who = decision.decidedBy ? ` by ${decision.decidedBy}` : "";
|
|
610
|
+
const why = decision.note ? ` Their reason: ${decision.note}` : "";
|
|
611
|
+
const reason =
|
|
612
|
+
decision.status === "rejected"
|
|
613
|
+
? `A person declined the change${who}, so nothing was changed.${why}`
|
|
614
|
+
: decision.status === "expired"
|
|
615
|
+
? "Nobody decided before the request expired, so nothing was changed."
|
|
616
|
+
: "The request was withdrawn, so nothing was changed.";
|
|
617
|
+
return { allowed: false, reason, approvalId: decision.id };
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
function show(value: unknown): string {
|
|
621
|
+
if (value === null || value === undefined) return "none";
|
|
622
|
+
if (Array.isArray(value)) return value.length ? value.join(", ") : "none";
|
|
623
|
+
if (typeof value === "boolean") return value ? "on" : "off";
|
|
624
|
+
return String(value);
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
function same(a: unknown, b: unknown): boolean {
|
|
628
|
+
const norm = (v: unknown) => (Array.isArray(v) ? JSON.stringify([...v].map(String).sort()) : JSON.stringify(v ?? null));
|
|
629
|
+
return norm(a) === norm(b);
|
|
630
|
+
}
|
|
631
|
+
|
|
632
|
+
/** Whether moving from `before` to `after` gives the key more room than it had. */
|
|
633
|
+
function loosening(key: keyof OpenRouterGuardrailSettings, before: unknown, after: unknown): boolean {
|
|
634
|
+
switch (key) {
|
|
635
|
+
case "limitUsd":
|
|
636
|
+
return after === null || (typeof before === "number" && typeof after === "number" && after > before);
|
|
637
|
+
case "enforceZdr":
|
|
638
|
+
return before === true && after !== true;
|
|
639
|
+
case "enablePaidModelTraining":
|
|
640
|
+
case "enableFreeModelTraining":
|
|
641
|
+
case "enableFreeModelPublication":
|
|
642
|
+
return after === true;
|
|
643
|
+
case "allowedModels":
|
|
644
|
+
case "allowedProviders":
|
|
645
|
+
case "allowedDataRegions": {
|
|
646
|
+
// null or empty means "anything": widening from a list to anything, or adding to the list.
|
|
647
|
+
const was = Array.isArray(before) ? before.map(String) : null;
|
|
648
|
+
const now = Array.isArray(after) ? after.map(String) : null;
|
|
649
|
+
if (!now || now.length === 0) return Boolean(was && was.length);
|
|
650
|
+
if (!was || was.length === 0) return false;
|
|
651
|
+
return now.some((item) => !was.includes(item));
|
|
652
|
+
}
|
|
653
|
+
case "ignoredModels":
|
|
654
|
+
case "ignoredProviders": {
|
|
655
|
+
const was = Array.isArray(before) ? before.map(String) : [];
|
|
656
|
+
const now = Array.isArray(after) ? after.map(String) : [];
|
|
657
|
+
return was.some((item) => !now.includes(item));
|
|
658
|
+
}
|
|
659
|
+
default:
|
|
660
|
+
return false;
|
|
661
|
+
}
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
function labelOf(kind: UsePolicyData): string {
|
|
665
|
+
return (
|
|
666
|
+
{ public: "public data", internal: "internal data", confidential: "confidential data", restricted: "restricted data", personal: "personal data", special: "special-category data" } as const
|
|
667
|
+
)[kind];
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
function digestOf(value: unknown): string {
|
|
671
|
+
const text = JSON.stringify(value, Object.keys((value ?? {}) as object).sort());
|
|
672
|
+
let hash = 0x811c9dc5;
|
|
673
|
+
for (let i = 0; i < text.length; i++) {
|
|
674
|
+
hash ^= text.charCodeAt(i);
|
|
675
|
+
hash = Math.imul(hash, 0x01000193) >>> 0;
|
|
676
|
+
}
|
|
677
|
+
return hash.toString(16).padStart(8, "0");
|
|
678
|
+
}
|