@deliverd/sdk 0.36.0 → 0.38.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.
@@ -39,8 +39,13 @@ import { askAboutCall, type CallDescription, type ToolApprovalOptions } from "./
39
39
  * out is a no, and the request expires with it, so nobody approves a step the
40
40
  * agent has stopped waiting for.
41
41
  *
42
- * Shapes follow `AgentAction` and `createAgent`'s `allow` option in
43
- * `@ui-sdk/core`'s agent docs (0.1.0-beta.1).
42
+ * When the browser's own agent can use the page too (WebMCP, through UI SDK's
43
+ * `registerTools`), pass `deliverdWebMcpAllow` as that `allow`. UI SDK runs it
44
+ * after the bridge's for each step the browser's agent asks for, inside the
45
+ * same `timeout`.
46
+ *
47
+ * Shapes follow `AgentAction`, `createAgent`'s `allow` option and
48
+ * `registerTools` in `@ui-sdk/core`'s agent docs (0.1.0-beta.1 and beta.2).
44
49
  */
45
50
 
46
51
  /** The step UI SDK hands to `allow`: its `AgentAction`. */
@@ -69,9 +74,23 @@ export interface DeliverdAllowOptions {
69
74
  headers?: Record<string, string> | (() => Record<string, string>);
70
75
  /** Told each answer, so the page can show a person's reason. */
71
76
  onAnswer?: (answer: UiSdkApprovalAnswer, step: UiSdkStep) => void;
77
+ /**
78
+ * Which agent asked, sent to your route so the approver can tell. `"webmcp"`
79
+ * means the browser's own agent, through `registerTools`. Letters, digits
80
+ * and dashes, up to 40.
81
+ */
82
+ via?: string;
72
83
  fetch?: typeof globalThis.fetch;
73
84
  }
74
85
 
86
+ /**
87
+ * Steps a person has already approved through Deliverd, by identity. UI SDK
88
+ * hands the same step object to the bridge's `allow` and then to the one
89
+ * `registerTools` was given, so the second can tell that the person was
90
+ * already asked about this very step and not ask them twice.
91
+ */
92
+ const approvedSteps = new WeakSet<object>();
93
+
75
94
  /**
76
95
  * UI SDK's `allow` hook, answered by a person through Deliverd.
77
96
  *
@@ -83,6 +102,7 @@ export function deliverdAllow(
83
102
  options: DeliverdAllowOptions
84
103
  ): (step: UiSdkStep, context?: { signal?: AbortSignal }) => Promise<boolean> {
85
104
  const needsPerson = options.when ?? ((step: UiSdkStep) => Boolean(step.confirm));
105
+ const via = options.via !== undefined && VIA.test(options.via) ? options.via : undefined;
86
106
  return async (step, context) => {
87
107
  if (!needsPerson(step)) return true;
88
108
  const doFetch = options.fetch ?? globalThis.fetch;
@@ -92,7 +112,7 @@ export function deliverdAllow(
92
112
  const response = await doFetch(options.endpoint, {
93
113
  method: "POST",
94
114
  headers: { "content-type": "application/json", ...headers },
95
- body: JSON.stringify({ step: pickStep(step), nonce: nonce() }),
115
+ body: JSON.stringify({ step: pickStep(step), nonce: nonce(), ...(via ? { via } : {}) }),
96
116
  signal: context?.signal,
97
117
  });
98
118
  const body = (await response.json().catch(() => null)) as Partial<UiSdkApprovalAnswer> | null;
@@ -111,10 +131,42 @@ export function deliverdAllow(
111
131
  answer = { allowed: false, reason: "The approval route could not be reached, so the step was not run." };
112
132
  }
113
133
  options.onAnswer?.(answer, step);
134
+ if (answer.allowed && typeof step === "object" && step !== null) approvedSteps.add(step);
114
135
  return answer.allowed;
115
136
  };
116
137
  }
117
138
 
139
+ /**
140
+ * The `allow` that UI SDK's `registerTools` asks for, answered by a person
141
+ * through Deliverd. Use it when the browser's own agent (ChatGPT's site tools,
142
+ * or any browser with WebMCP) can use your page:
143
+ *
144
+ * ```ts
145
+ * registerTools(agent, {
146
+ * allow: deliverdWebMcpAllow({ endpoint: "/api/deliverd/ui-approval" }),
147
+ * });
148
+ * ```
149
+ *
150
+ * It asks about marked steps by default, as `deliverdAllow` does, and tells
151
+ * your route the browser's agent asked (`via: "webmcp"`). A step the bridge's
152
+ * own `deliverdAllow` already put to a person is not asked about again.
153
+ *
154
+ * Do not pass `allow: () => true` to `registerTools` unless the bridge has an
155
+ * `allow` that asks a person: with no bridge `allow`, UI SDK lets the browser's
156
+ * agent through a `data-agent-confirm` mark on that `true` alone.
157
+ */
158
+ export function deliverdWebMcpAllow(
159
+ options: DeliverdAllowOptions
160
+ ): (step: UiSdkStep, context?: { signal?: AbortSignal }) => Promise<boolean> {
161
+ const ask = deliverdAllow({ ...options, via: options.via ?? "webmcp" });
162
+ return async (step, context) => {
163
+ // The bridge's own deliverdAllow said yes to this very step a moment ago.
164
+ // Used once: the same object never counts for a later step.
165
+ if (typeof step === "object" && step !== null && approvedSteps.delete(step)) return true;
166
+ return ask(step, context);
167
+ };
168
+ }
169
+
118
170
  export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "when" | "describe"> {
119
171
  /**
120
172
  * Which steps go to a person, decided on the server. Default: those on a
@@ -122,9 +174,9 @@ export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "wh
122
174
  * the browser only sends steps it wants a person for, so anything else
123
175
  * arriving here was not sent by `deliverdAllow`.
124
176
  */
125
- when?: (step: UiSdkStep, request: Request) => boolean | Promise<boolean>;
177
+ when?: (step: UiSdkStep, request: Request, context: UiSdkAskContext) => boolean | Promise<boolean>;
126
178
  /** What the approver reads. Built from the mark's sentence, the control and its values when omitted. */
127
- describe?: (step: UiSdkStep) => CallDescription;
179
+ describe?: (step: UiSdkStep, context: UiSdkAskContext) => CallDescription;
128
180
  /**
129
181
  * How long to wait for the person. Default four minutes, inside UI SDK's
130
182
  * own five-minute wait and a typical function limit. Raise all three together.
@@ -134,6 +186,12 @@ export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "wh
134
186
  expiresIn?: Duration;
135
187
  }
136
188
 
189
+ /** What the page said about who asked. The page says it; nothing checks it. */
190
+ export interface UiSdkAskContext {
191
+ /** `"webmcp"` when the browser's own agent asked, through `deliverdWebMcpAllow`. */
192
+ via?: string;
193
+ }
194
+
137
195
  export const UI_SDK_DEFAULT_TIMEOUT: Duration = "4m";
138
196
 
139
197
  /**
@@ -160,8 +218,9 @@ export function uiSdkApprovalRoute(options: UiSdkApprovalRouteOptions): (request
160
218
  }
161
219
  const parsed = readBody(raw);
162
220
  if (!parsed) return json({ allowed: false, reason: "The step could not be read." }, 400);
163
- const { step, nonce: id } = parsed;
164
- if (!(await needsPerson(step, request))) {
221
+ const { step, nonce: id, via } = parsed;
222
+ const context: UiSdkAskContext = via ? { via } : {};
223
+ if (!(await needsPerson(step, request, context))) {
165
224
  return json({ allowed: false, reason: "This step is not one this route asks a person about." }, 403);
166
225
  }
167
226
  const name = stepName(step);
@@ -172,10 +231,10 @@ export function uiSdkApprovalRoute(options: UiSdkApprovalRouteOptions): (request
172
231
  {
173
232
  ...options,
174
233
  when: undefined,
175
- describe: () => describe(step),
234
+ describe: () => describe(step, context),
176
235
  timeout,
177
236
  expiresIn: options.expiresIn ?? timeout,
178
- metadata: { ...options.metadata, source: "ui-sdk" },
237
+ metadata: { ...options.metadata, source: "ui-sdk", ...(via ? { via } : {}) },
179
238
  },
180
239
  request.signal
181
240
  );
@@ -187,13 +246,16 @@ export function uiSdkApprovalRoute(options: UiSdkApprovalRouteOptions): (request
187
246
  }
188
247
 
189
248
  /** What an approver reads about a step, when the app did not write it. */
190
- export function describeStep(step: UiSdkStep): CallDescription {
249
+ export function describeStep(step: UiSdkStep, context: UiSdkAskContext = {}): CallDescription {
191
250
  const target = step.label ? `"${step.label}"` : `the ${step.component}`;
192
251
  const verb = step.action === "press" ? "press" : step.action === "setValue" ? "set" : step.action;
193
252
  const values = (step.args ?? []).map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg))).join(", ");
194
253
  const lines = [
195
254
  step.confirm ? `The app says this: ${step.confirm}` : undefined,
196
255
  `An agent wants to ${verb} ${target}${values ? ` (${truncate(values, 500)})` : ""} in the app.`,
256
+ context.via === "webmcp"
257
+ ? "It is the browser's own agent, using the page through WebMCP, not an agent the app runs."
258
+ : undefined,
197
259
  ].filter(Boolean);
198
260
  return {
199
261
  title: truncate(step.confirm ?? `Let the agent ${verb} ${target}`, 200),
@@ -203,6 +265,7 @@ export function describeStep(step: UiSdkStep): CallDescription {
203
265
  }
204
266
 
205
267
  const BODY_MAX = 16_000;
268
+ const VIA = /^[a-z0-9-]{1,40}$/;
206
269
 
207
270
  function stepName(step: UiSdkStep): string {
208
271
  return step.label ? `${step.action} "${step.label}"` : `${step.action} ${step.component}`;
@@ -220,9 +283,10 @@ function pickStep(step: UiSdkStep): UiSdkStep {
220
283
  };
221
284
  }
222
285
 
223
- function readBody(raw: unknown): { step: UiSdkStep; nonce: string } | null {
286
+ function readBody(raw: unknown): { step: UiSdkStep; nonce: string; via?: string } | null {
224
287
  if (typeof raw !== "object" || raw === null) return null;
225
- const { step, nonce: id } = raw as { step?: unknown; nonce?: unknown };
288
+ const { step, nonce: id, via } = raw as { step?: unknown; nonce?: unknown; via?: unknown };
289
+ if (via !== undefined && (typeof via !== "string" || !VIA.test(via))) return null;
226
290
  if (typeof id !== "string" || id.length === 0 || id.length > 100) return null;
227
291
  if (typeof step !== "object" || step === null) return null;
228
292
  const s = step as Record<string, unknown>;
@@ -231,7 +295,7 @@ function readBody(raw: unknown): { step: UiSdkStep; nonce: string } | null {
231
295
  if (s.label !== undefined && !str(s.label)) return null;
232
296
  if (s.confirm !== undefined && !str(s.confirm)) return null;
233
297
  if (s.args !== undefined && !Array.isArray(s.args)) return null;
234
- return { step: pickStep(s as unknown as UiSdkStep), nonce: id };
298
+ return { step: pickStep(s as unknown as UiSdkStep), nonce: id, ...(typeof via === "string" ? { via } : {}) };
235
299
  }
236
300
 
237
301
  function json(body: UiSdkApprovalAnswer | { allowed: false; reason: string }, status: number): Response {
package/src/governance.ts CHANGED
@@ -18,6 +18,7 @@ import type {
18
18
  GovernanceSummaryInput,
19
19
  IctRegister,
20
20
  ListIncidentsInput,
21
+ UsePolicy,
21
22
  ModelChangeInput,
22
23
  ModelChangeResult,
23
24
  RegisterAiSystemInput,
@@ -192,6 +193,15 @@ export class AiGovernance {
192
193
  return this.http.request<IctRegister>({ method: "GET", path: "/governance/ict-register", signal });
193
194
  }
194
195
 
196
+ /**
197
+ * The AI use policy: which data may go into which kind of AI tool. Read
198
+ * only; a person changes it in the app (Governance → AI use policy).
199
+ */
200
+ async aiUsePolicy(signal?: AbortSignal): Promise<UsePolicy> {
201
+ const { policy } = await this.http.request<{ policy: UsePolicy }>({ method: "GET", path: "/governance/ai-use-policy", signal });
202
+ return policy;
203
+ }
204
+
195
205
  /** The organisation's AI governance in counts, optionally narrowed. Never a compliance percentage. */
196
206
  summary(input: GovernanceSummaryInput = {}, signal?: AbortSignal): Promise<GovernanceSummary> {
197
207
  return this.http.request<GovernanceSummary>({