@deliverd/sdk 0.36.0 → 0.37.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 CHANGED
@@ -921,6 +921,20 @@ files"). A no, a wait that runs out, or a route that fails all leave the
921
921
  control untouched. The route waits four minutes by default; raise its
922
922
  `timeout`, the bridge's `timeout` and your function's limit together.
923
923
 
924
+ If the browser's own agent can use the page too, through WebMCP, give
925
+ `registerTools` the WebMCP version. The approver is told the browser's agent
926
+ asked, and a step the bridge already put to a person is not asked twice:
927
+
928
+ ```ts
929
+ import { deliverdWebMcpAllow } from "@deliverd/sdk/adapters";
930
+
931
+ registerTools(agent, { allow: deliverdWebMcpAllow({ endpoint: "/api/deliverd/ui-approval" }) });
932
+ ```
933
+
934
+ Don't pass `allow: () => true` there unless the bridge itself has an `allow`
935
+ that asks a person: without one, UI SDK lets the browser's agent through a
936
+ `data-agent-confirm` mark on that `true` alone.
937
+
924
938
  **LangGraph** — pause the graph rather than a process, and resume it from the callback:
925
939
 
926
940
  ```ts
@@ -20,8 +20,8 @@ export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraAppr
20
20
  export type { MastraApprovingAgent, MastraOutput } from "./mastra.js";
21
21
  export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
22
22
  export type { MuseFunctionCall, MuseFunctionCallOutput, MuseToolApprovalOptions, MuseToolCall, MuseToolMessage, MuseToolRunner, } from "./muse-spark.js";
23
- export { deliverdAllow, describeStep, uiSdkApprovalRoute, UI_SDK_DEFAULT_TIMEOUT } from "./ui-sdk.js";
24
- export type { DeliverdAllowOptions, UiSdkApprovalAnswer, UiSdkApprovalRouteOptions, UiSdkStep } from "./ui-sdk.js";
23
+ export { deliverdAllow, deliverdWebMcpAllow, describeStep, uiSdkApprovalRoute, UI_SDK_DEFAULT_TIMEOUT } from "./ui-sdk.js";
24
+ export type { DeliverdAllowOptions, UiSdkApprovalAnswer, UiSdkApprovalRouteOptions, UiSdkAskContext, UiSdkStep } from "./ui-sdk.js";
25
25
  export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
26
26
  export type { Approver, CallDescription, CallOutcome, ToolApprovalOptions } from "./shared.js";
27
27
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACtG,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC3H,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpI,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
@@ -13,5 +13,5 @@ export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.
13
13
  export { approveInGraph, resumeFromCallback } from "./langgraph.js";
14
14
  export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraApproval } from "./mastra.js";
15
15
  export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
16
- export { deliverdAllow, describeStep, uiSdkApprovalRoute, UI_SDK_DEFAULT_TIMEOUT } from "./ui-sdk.js";
16
+ export { deliverdAllow, deliverdWebMcpAllow, describeStep, uiSdkApprovalRoute, UI_SDK_DEFAULT_TIMEOUT } from "./ui-sdk.js";
17
17
  export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
@@ -38,8 +38,13 @@ import { type CallDescription, type ToolApprovalOptions } from "./shared.js";
38
38
  * out is a no, and the request expires with it, so nobody approves a step the
39
39
  * agent has stopped waiting for.
40
40
  *
41
- * Shapes follow `AgentAction` and `createAgent`'s `allow` option in
42
- * `@ui-sdk/core`'s agent docs (0.1.0-beta.1).
41
+ * When the browser's own agent can use the page too (WebMCP, through UI SDK's
42
+ * `registerTools`), pass `deliverdWebMcpAllow` as that `allow`. UI SDK runs it
43
+ * after the bridge's for each step the browser's agent asks for, inside the
44
+ * same `timeout`.
45
+ *
46
+ * Shapes follow `AgentAction`, `createAgent`'s `allow` option and
47
+ * `registerTools` in `@ui-sdk/core`'s agent docs (0.1.0-beta.1 and beta.2).
43
48
  */
44
49
  /** The step UI SDK hands to `allow`: its `AgentAction`. */
45
50
  export interface UiSdkStep {
@@ -71,6 +76,12 @@ export interface DeliverdAllowOptions {
71
76
  headers?: Record<string, string> | (() => Record<string, string>);
72
77
  /** Told each answer, so the page can show a person's reason. */
73
78
  onAnswer?: (answer: UiSdkApprovalAnswer, step: UiSdkStep) => void;
79
+ /**
80
+ * Which agent asked, sent to your route so the approver can tell. `"webmcp"`
81
+ * means the browser's own agent, through `registerTools`. Letters, digits
82
+ * and dashes, up to 40.
83
+ */
84
+ via?: string;
74
85
  fetch?: typeof globalThis.fetch;
75
86
  }
76
87
  /**
@@ -83,6 +94,28 @@ export interface DeliverdAllowOptions {
83
94
  export declare function deliverdAllow(options: DeliverdAllowOptions): (step: UiSdkStep, context?: {
84
95
  signal?: AbortSignal;
85
96
  }) => Promise<boolean>;
97
+ /**
98
+ * The `allow` that UI SDK's `registerTools` asks for, answered by a person
99
+ * through Deliverd. Use it when the browser's own agent (ChatGPT's site tools,
100
+ * or any browser with WebMCP) can use your page:
101
+ *
102
+ * ```ts
103
+ * registerTools(agent, {
104
+ * allow: deliverdWebMcpAllow({ endpoint: "/api/deliverd/ui-approval" }),
105
+ * });
106
+ * ```
107
+ *
108
+ * It asks about marked steps by default, as `deliverdAllow` does, and tells
109
+ * your route the browser's agent asked (`via: "webmcp"`). A step the bridge's
110
+ * own `deliverdAllow` already put to a person is not asked about again.
111
+ *
112
+ * Do not pass `allow: () => true` to `registerTools` unless the bridge has an
113
+ * `allow` that asks a person: with no bridge `allow`, UI SDK lets the browser's
114
+ * agent through a `data-agent-confirm` mark on that `true` alone.
115
+ */
116
+ export declare function deliverdWebMcpAllow(options: DeliverdAllowOptions): (step: UiSdkStep, context?: {
117
+ signal?: AbortSignal;
118
+ }) => Promise<boolean>;
86
119
  export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "when" | "describe"> {
87
120
  /**
88
121
  * Which steps go to a person, decided on the server. Default: those on a
@@ -90,9 +123,9 @@ export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "wh
90
123
  * the browser only sends steps it wants a person for, so anything else
91
124
  * arriving here was not sent by `deliverdAllow`.
92
125
  */
93
- when?: (step: UiSdkStep, request: Request) => boolean | Promise<boolean>;
126
+ when?: (step: UiSdkStep, request: Request, context: UiSdkAskContext) => boolean | Promise<boolean>;
94
127
  /** What the approver reads. Built from the mark's sentence, the control and its values when omitted. */
95
- describe?: (step: UiSdkStep) => CallDescription;
128
+ describe?: (step: UiSdkStep, context: UiSdkAskContext) => CallDescription;
96
129
  /**
97
130
  * How long to wait for the person. Default four minutes, inside UI SDK's
98
131
  * own five-minute wait and a typical function limit. Raise all three together.
@@ -101,6 +134,11 @@ export interface UiSdkApprovalRouteOptions extends Omit<ToolApprovalOptions, "wh
101
134
  /** How long the request stays open. Default: the same as `timeout`. */
102
135
  expiresIn?: Duration;
103
136
  }
137
+ /** What the page said about who asked. The page says it; nothing checks it. */
138
+ export interface UiSdkAskContext {
139
+ /** `"webmcp"` when the browser's own agent asked, through `deliverdWebMcpAllow`. */
140
+ via?: string;
141
+ }
104
142
  export declare const UI_SDK_DEFAULT_TIMEOUT: Duration;
105
143
  /**
106
144
  * The server half: a fetch-style `POST` handler (Next.js route handlers, Hono,
@@ -112,5 +150,5 @@ export declare const UI_SDK_DEFAULT_TIMEOUT: Duration;
112
150
  */
113
151
  export declare function uiSdkApprovalRoute(options: UiSdkApprovalRouteOptions): (request: Request) => Promise<Response>;
114
152
  /** What an approver reads about a step, when the app did not write it. */
115
- export declare function describeStep(step: UiSdkStep): CallDescription;
153
+ export declare function describeStep(step: UiSdkStep, context?: UiSdkAskContext): CallDescription;
116
154
  //# sourceMappingURL=ui-sdk.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"ui-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ui-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,MAAM,mBAAmB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IACpC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAClE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAgC3E;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/F;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,wGAAwG;IACxG,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,eAAe,CAAC;IAChD;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,QAAQ,CAAC;CACtB;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAe,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAwC9G;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAa7D"}
1
+ {"version":3,"file":"ui-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ui-sdk.ts"],"names":[],"mappings":"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"}
@@ -1,4 +1,11 @@
1
1
  import { askAboutCall } from "./shared.js";
2
+ /**
3
+ * Steps a person has already approved through Deliverd, by identity. UI SDK
4
+ * hands the same step object to the bridge's `allow` and then to the one
5
+ * `registerTools` was given, so the second can tell that the person was
6
+ * already asked about this very step and not ask them twice.
7
+ */
8
+ const approvedSteps = new WeakSet();
2
9
  /**
3
10
  * UI SDK's `allow` hook, answered by a person through Deliverd.
4
11
  *
@@ -8,6 +15,7 @@ import { askAboutCall } from "./shared.js";
8
15
  */
9
16
  export function deliverdAllow(options) {
10
17
  const needsPerson = options.when ?? ((step) => Boolean(step.confirm));
18
+ const via = options.via !== undefined && VIA.test(options.via) ? options.via : undefined;
11
19
  return async (step, context) => {
12
20
  if (!needsPerson(step))
13
21
  return true;
@@ -18,7 +26,7 @@ export function deliverdAllow(options) {
18
26
  const response = await doFetch(options.endpoint, {
19
27
  method: "POST",
20
28
  headers: { "content-type": "application/json", ...headers },
21
- body: JSON.stringify({ step: pickStep(step), nonce: nonce() }),
29
+ body: JSON.stringify({ step: pickStep(step), nonce: nonce(), ...(via ? { via } : {}) }),
22
30
  signal: context?.signal,
23
31
  });
24
32
  const body = (await response.json().catch(() => null));
@@ -38,9 +46,40 @@ export function deliverdAllow(options) {
38
46
  answer = { allowed: false, reason: "The approval route could not be reached, so the step was not run." };
39
47
  }
40
48
  options.onAnswer?.(answer, step);
49
+ if (answer.allowed && typeof step === "object" && step !== null)
50
+ approvedSteps.add(step);
41
51
  return answer.allowed;
42
52
  };
43
53
  }
54
+ /**
55
+ * The `allow` that UI SDK's `registerTools` asks for, answered by a person
56
+ * through Deliverd. Use it when the browser's own agent (ChatGPT's site tools,
57
+ * or any browser with WebMCP) can use your page:
58
+ *
59
+ * ```ts
60
+ * registerTools(agent, {
61
+ * allow: deliverdWebMcpAllow({ endpoint: "/api/deliverd/ui-approval" }),
62
+ * });
63
+ * ```
64
+ *
65
+ * It asks about marked steps by default, as `deliverdAllow` does, and tells
66
+ * your route the browser's agent asked (`via: "webmcp"`). A step the bridge's
67
+ * own `deliverdAllow` already put to a person is not asked about again.
68
+ *
69
+ * Do not pass `allow: () => true` to `registerTools` unless the bridge has an
70
+ * `allow` that asks a person: with no bridge `allow`, UI SDK lets the browser's
71
+ * agent through a `data-agent-confirm` mark on that `true` alone.
72
+ */
73
+ export function deliverdWebMcpAllow(options) {
74
+ const ask = deliverdAllow({ ...options, via: options.via ?? "webmcp" });
75
+ return async (step, context) => {
76
+ // The bridge's own deliverdAllow said yes to this very step a moment ago.
77
+ // Used once: the same object never counts for a later step.
78
+ if (typeof step === "object" && step !== null && approvedSteps.delete(step))
79
+ return true;
80
+ return ask(step, context);
81
+ };
82
+ }
44
83
  export const UI_SDK_DEFAULT_TIMEOUT = "4m";
45
84
  /**
46
85
  * The server half: a fetch-style `POST` handler (Next.js route handlers, Hono,
@@ -70,30 +109,34 @@ export function uiSdkApprovalRoute(options) {
70
109
  const parsed = readBody(raw);
71
110
  if (!parsed)
72
111
  return json({ allowed: false, reason: "The step could not be read." }, 400);
73
- const { step, nonce: id } = parsed;
74
- if (!(await needsPerson(step, request))) {
112
+ const { step, nonce: id, via } = parsed;
113
+ const context = via ? { via } : {};
114
+ if (!(await needsPerson(step, request, context))) {
75
115
  return json({ allowed: false, reason: "This step is not one this route asks a person about." }, 403);
76
116
  }
77
117
  const name = stepName(step);
78
118
  const outcome = await askAboutCall(name, { component: step.component, ref: step.ref, action: step.action, args: step.args ?? [] }, `ui-sdk:${await sha256(canonical({ step, id }))}`, {
79
119
  ...options,
80
120
  when: undefined,
81
- describe: () => describe(step),
121
+ describe: () => describe(step, context),
82
122
  timeout,
83
123
  expiresIn: options.expiresIn ?? timeout,
84
- metadata: { ...options.metadata, source: "ui-sdk" },
124
+ metadata: { ...options.metadata, source: "ui-sdk", ...(via ? { via } : {}) },
85
125
  }, request.signal);
86
126
  return json(outcome.allowed ? { allowed: true, decidedBy: outcome.decidedBy } : { allowed: false, reason: outcome.reason }, 200);
87
127
  };
88
128
  }
89
129
  /** What an approver reads about a step, when the app did not write it. */
90
- export function describeStep(step) {
130
+ export function describeStep(step, context = {}) {
91
131
  const target = step.label ? `"${step.label}"` : `the ${step.component}`;
92
132
  const verb = step.action === "press" ? "press" : step.action === "setValue" ? "set" : step.action;
93
133
  const values = (step.args ?? []).map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg))).join(", ");
94
134
  const lines = [
95
135
  step.confirm ? `The app says this: ${step.confirm}` : undefined,
96
136
  `An agent wants to ${verb} ${target}${values ? ` (${truncate(values, 500)})` : ""} in the app.`,
137
+ context.via === "webmcp"
138
+ ? "It is the browser's own agent, using the page through WebMCP, not an agent the app runs."
139
+ : undefined,
97
140
  ].filter(Boolean);
98
141
  return {
99
142
  title: truncate(step.confirm ?? `Let the agent ${verb} ${target}`, 200),
@@ -102,6 +145,7 @@ export function describeStep(step) {
102
145
  };
103
146
  }
104
147
  const BODY_MAX = 16_000;
148
+ const VIA = /^[a-z0-9-]{1,40}$/;
105
149
  function stepName(step) {
106
150
  return step.label ? `${step.action} "${step.label}"` : `${step.action} ${step.component}`;
107
151
  }
@@ -119,7 +163,9 @@ function pickStep(step) {
119
163
  function readBody(raw) {
120
164
  if (typeof raw !== "object" || raw === null)
121
165
  return null;
122
- const { step, nonce: id } = raw;
166
+ const { step, nonce: id, via } = raw;
167
+ if (via !== undefined && (typeof via !== "string" || !VIA.test(via)))
168
+ return null;
123
169
  if (typeof id !== "string" || id.length === 0 || id.length > 100)
124
170
  return null;
125
171
  if (typeof step !== "object" || step === null)
@@ -134,7 +180,7 @@ function readBody(raw) {
134
180
  return null;
135
181
  if (s.args !== undefined && !Array.isArray(s.args))
136
182
  return null;
137
- return { step: pickStep(s), nonce: id };
183
+ return { step: pickStep(s), nonce: id, ...(typeof via === "string" ? { via } : {}) };
138
184
  }
139
185
  function json(body, status) {
140
186
  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
@@ -43,7 +43,7 @@
43
43
  * **Add the version here when you publish it, not before.** An entry is a
44
44
  * claim that `npm install @deliverd/sdk@x` works today.
45
45
  */
46
- export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0", "0.35.0"];
46
+ export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0", "0.35.0", "0.36.0"];
47
47
  /**
48
48
  * A fingerprint of what each *published* version recorded.
49
49
  *
@@ -1 +1 @@
1
- {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,2aA4CnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqHzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAm9jCtD,CAAC"}
1
+ {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,qbA6CnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuHzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAu7mCtD,CAAC"}