@deliverd/sdk 0.25.1 → 0.26.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.
Files changed (47) hide show
  1. package/README.md +65 -0
  2. package/dist/adapters/index.d.ts +4 -0
  3. package/dist/adapters/index.d.ts.map +1 -1
  4. package/dist/adapters/index.js +2 -0
  5. package/dist/adapters/mastra.d.ts +81 -0
  6. package/dist/adapters/mastra.d.ts.map +1 -0
  7. package/dist/adapters/mastra.js +54 -0
  8. package/dist/adapters/muse-spark.d.ts +79 -0
  9. package/dist/adapters/muse-spark.d.ts.map +1 -0
  10. package/dist/adapters/muse-spark.js +59 -0
  11. package/dist/adapters/shared.d.ts +2 -1
  12. package/dist/adapters/shared.d.ts.map +1 -1
  13. package/dist/data-screen.d.ts +233 -0
  14. package/dist/data-screen.d.ts.map +1 -0
  15. package/dist/data-screen.js +389 -0
  16. package/dist/dev.d.ts.map +1 -1
  17. package/dist/dev.js +42 -2
  18. package/dist/governance.d.ts +94 -0
  19. package/dist/governance.d.ts.map +1 -0
  20. package/dist/governance.js +166 -0
  21. package/dist/index.d.ts +27 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +30 -0
  24. package/dist/released.d.ts +1 -1
  25. package/dist/released.d.ts.map +1 -1
  26. package/dist/released.js +1265 -0
  27. package/dist/screen.d.ts +85 -0
  28. package/dist/screen.d.ts.map +1 -0
  29. package/dist/screen.js +69 -0
  30. package/dist/tasks.d.ts +38 -1
  31. package/dist/tasks.d.ts.map +1 -1
  32. package/dist/tasks.js +67 -0
  33. package/dist/types.d.ts +589 -3
  34. package/dist/types.d.ts.map +1 -1
  35. package/package.json +2 -2
  36. package/src/adapters/index.ts +11 -0
  37. package/src/adapters/mastra.ts +118 -0
  38. package/src/adapters/muse-spark.ts +147 -0
  39. package/src/adapters/shared.ts +2 -1
  40. package/src/data-screen.ts +533 -0
  41. package/src/dev.ts +45 -2
  42. package/src/governance.ts +204 -0
  43. package/src/index.ts +43 -0
  44. package/src/released.ts +1265 -0
  45. package/src/screen.ts +144 -0
  46. package/src/tasks.ts +88 -0
  47. package/src/types.ts +577 -3
package/README.md CHANGED
@@ -324,6 +324,47 @@ A finding of kind `decision` is a suggestion until a person confirms it.
324
324
  `task.requestDecisionApproval(findingId)` puts it to somebody. Only a person
325
325
  changes what a task is for; an agent proposes that as a finding too.
326
326
 
327
+ ## Compliance Mode
328
+
329
+ On Business and Enterprise, a task can be governed: the AI system doing the
330
+ work, its purpose, owners, risk, data and oversight, the controls that follow
331
+ from them, and a gate that says whether the work may proceed.
332
+
333
+ ```ts
334
+ const system = await deliverd.governance.aiSystems.register({
335
+ name: "Claims triage",
336
+ provider: "Anthropic",
337
+ model: "claude-opus",
338
+ promptHash: "sha256:9f2c…", // a digest, never the prompt
339
+ });
340
+
341
+ await task.govern({ aiSystemId: system.id, purpose: "Route claims", risk: "high", personalData: true });
342
+ await task.submitEvidence({ type: "model_evaluation", title: "Eval run", controls: ["model_evaluation"], results });
343
+ await task.requestControlApproval("deployment_approval");
344
+
345
+ const gate = await task.checkGovernanceGate({ action: "deploy" });
346
+ if (!gate.allowed) throw new Error(gate.reason);
347
+
348
+ const pack = await task.evidencePack(); // profile, controls, evidence, decisions, timeline, digest
349
+ ```
350
+
351
+ `deliverd.governance` covers the organisation as a whole:
352
+
353
+ - `checkAuthority({ action })` says whether this agent may `send`, `deploy`,
354
+ `delete` and the rest on its own, only with approval, or not at all.
355
+ - `incidents.report()`, `get()`, `list()` and `draftReport()` record AI
356
+ incidents and draft the DORA reports a person signs off.
357
+ - `aiSystems.recordModelChange()` records a new model or prompt, and every
358
+ task that uses the system is reassessed. `task.triggerReassessment(reason)`
359
+ asks for one by hand.
360
+ - `frameworks()`, `frameworkMapping({ taskId })` and `createCustomFramework()`
361
+ show how requirements map onto controls. `ictRegister()` and `summary()`
362
+ are read-only views.
363
+
364
+ An agent can raise a risk or add facts. Only a person can lower them, set
365
+ thresholds, waive a control or resolve an incident. Every answer records
366
+ governance and certifies nothing.
367
+
327
368
  ## Evidence
328
369
 
329
370
  Show your working. One call assembles the whole record of a piece of work —
@@ -696,6 +737,30 @@ import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
696
737
  const result = await runWithDeliverdApprovals((input) => run(agent, input), "Refund order 1042", { deliverd });
697
738
  ```
698
739
 
740
+ **Mastra** — mark tools `requireApproval: true` (or pass `requireToolApproval`), then:
741
+
742
+ ```ts
743
+ import { generateWithDeliverdApprovals } from "@deliverd/sdk/adapters";
744
+
745
+ const output = await generateWithDeliverdApprovals(agent, agent.generate("Refund order 1042", { requireToolApproval: true }), { deliverd });
746
+ ```
747
+
748
+ Each suspended call is approved with `agent.approveToolCallGenerate` or declined
749
+ with `agent.declineToolCallGenerate`, and the person's reason reaches the model.
750
+
751
+ **Muse Spark** (Meta Model API) — the loop runs the calls, so hand them over with the function that runs them:
752
+
753
+ ```ts
754
+ import { runMuseFunctionCalls } from "@deliverd/sdk/adapters";
755
+
756
+ const results = await runMuseFunctionCalls(resp.output, runTool, { deliverd, when: (tool) => tool === "refund" });
757
+ resp = await muse.responses.create({ model: "muse-spark-1.1", input: results, tools, previous_response_id: resp.id });
758
+ ```
759
+
760
+ Only approved calls run; a declined one's result tells the model a person said
761
+ no, and why. `runMuseToolCalls(message, runTool, { deliverd })` does the same
762
+ for Chat Completions' `tool_calls`.
763
+
699
764
  **LangGraph** — pause the graph rather than a process, and resume it from the callback:
700
765
 
701
766
  ```ts
@@ -14,6 +14,10 @@ export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.
14
14
  export type { OpenAiApprovalItem, OpenAiInterruptedResult } from "./openai-agents.js";
15
15
  export { approveInGraph, resumeFromCallback } from "./langgraph.js";
16
16
  export type { DeliverdInterruptValue, GraphApprovalRecord, GraphApprover, GraphDecision } from "./langgraph.js";
17
+ export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraApproval } from "./mastra.js";
18
+ export type { MastraApprovingAgent, MastraOutput } from "./mastra.js";
19
+ export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
20
+ export type { MuseFunctionCall, MuseFunctionCallOutput, MuseToolApprovalOptions, MuseToolCall, MuseToolMessage, MuseToolRunner, } from "./muse-spark.js";
17
21
  export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
18
22
  export type { Approver, CallDescription, CallOutcome, ToolApprovalOptions } from "./shared.js";
19
23
  //# 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,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,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,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,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
@@ -10,4 +10,6 @@ export { deliverdCanUseTool } from "./claude-agent-sdk.js";
10
10
  export { deliverdToolApproval } from "./ai-sdk.js";
11
11
  export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.js";
12
12
  export { approveInGraph, resumeFromCallback } from "./langgraph.js";
13
+ export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraApproval } from "./mastra.js";
14
+ export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
13
15
  export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
@@ -0,0 +1,81 @@
1
+ import { type ToolApprovalOptions } from "./shared.js";
2
+ /**
3
+ * Mastra: a person approves an agent's tool calls, through Deliverd.
4
+ *
5
+ * Mark the tools that need a person as Mastra already has you do —
6
+ * `createTool({ requireApproval: true })`, or `requireToolApproval` on the
7
+ * call — and a run that reaches one stops with `finishReason: "suspended"`.
8
+ * Instead of building your own prompt:
9
+ *
10
+ * ```ts
11
+ * import { Deliverd } from "@deliverd/sdk";
12
+ * import { generateWithDeliverdApprovals } from "@deliverd/sdk/adapters";
13
+ *
14
+ * const output = await generateWithDeliverdApprovals(
15
+ * agent,
16
+ * agent.generate("Refund order 1042", { requireToolApproval: true }),
17
+ * { deliverd: new Deliverd(), approvers: ["finance"] }
18
+ * );
19
+ * console.log(output.text);
20
+ * ```
21
+ *
22
+ * Each suspended call becomes a request in Deliverd. Approved, it is
23
+ * `agent.approveToolCallGenerate({ runId, toolCallId })` and the tool runs;
24
+ * declined, it is `agent.declineToolCallGenerate({ runId, toolCallId, reason })`
25
+ * and Mastra hands the person's reason to the model in place of its default
26
+ * "not approved". The run resumes until nothing is waiting on a person.
27
+ * `resolveMastraApproval` does one round, for a loop you own.
28
+ *
29
+ * A run suspended by a tool's own `suspend()` — waiting on data, not on a
30
+ * yes or no — is returned as it is, for you to resume.
31
+ *
32
+ * Shapes follow `@mastra/core` 1.78.0's type definitions:
33
+ * `Agent.approveToolCallGenerate` and `Agent.declineToolCallGenerate` in
34
+ * `dist/agent/agent.d.ts`; `FullOutput`'s `finishReason`, `runId` and
35
+ * `suspendPayload` in `dist/stream/base/output.d.ts`; and the payload of a
36
+ * `tool-call-approval` chunk, `ToolCallApprovalPayload` (`toolCallId`,
37
+ * `toolName`, `args`), against `ToolCallSuspendedPayload`, which also carries
38
+ * the tool's own `suspendPayload`, in `dist/stream/types.d.ts`.
39
+ */
40
+ /** The part of a Mastra generate output this adapter reads. */
41
+ export interface MastraOutput {
42
+ finishReason?: string;
43
+ runId?: string;
44
+ /** For an approval: `{ toolCallId, toolName, args }`. */
45
+ suspendPayload?: unknown;
46
+ }
47
+ /** The part of a Mastra `Agent` this adapter calls. */
48
+ export interface MastraApprovingAgent<Output extends MastraOutput = MastraOutput> {
49
+ approveToolCallGenerate(options: {
50
+ runId: string;
51
+ toolCallId?: string;
52
+ }): Promise<Output>;
53
+ declineToolCallGenerate(options: {
54
+ runId: string;
55
+ toolCallId?: string;
56
+ reason?: string;
57
+ }): Promise<Output>;
58
+ }
59
+ /** The tool call a suspended output is waiting on a person for, or null when it is not. */
60
+ export declare function pendingMastraApproval(output: MastraOutput): {
61
+ runId: string;
62
+ toolCallId: string;
63
+ toolName: string;
64
+ args: unknown;
65
+ } | null;
66
+ /**
67
+ * Decide the call a suspended output is waiting on, and resume the run.
68
+ * Returns the resumed run's output, or null when nothing was waiting on a
69
+ * person.
70
+ */
71
+ export declare function resolveMastraApproval<Output extends MastraOutput>(agent: MastraApprovingAgent<Output>, output: MastraOutput, options: ToolApprovalOptions): Promise<Output | null>;
72
+ /**
73
+ * Resume a Mastra run until nothing is waiting on a person.
74
+ *
75
+ * `first` is the output of `agent.generate(…)`, or the promise of it. A cap
76
+ * on rounds stops an agent that keeps asking from waiting forever.
77
+ */
78
+ export declare function generateWithDeliverdApprovals<Output extends MastraOutput>(agent: MastraApprovingAgent<Output>, first: Output | Promise<Output>, options: ToolApprovalOptions & {
79
+ maxRounds?: number;
80
+ }): Promise<Output>;
81
+ //# sourceMappingURL=mastra.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../src/adapters/mastra.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAC9E,uBAAuB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1F,uBAAuB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5G;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAa/E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,SAAS,YAAY,EACrE,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,SAAS,YAAY,EAC7E,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACnC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAC/B,OAAO,EAAE,mBAAmB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,OAAO,CAAC,MAAM,CAAC,CAYjB"}
@@ -0,0 +1,54 @@
1
+ import { askAboutCall } from "./shared.js";
2
+ /** The tool call a suspended output is waiting on a person for, or null when it is not. */
3
+ export function pendingMastraApproval(output) {
4
+ if (output.finishReason !== "suspended" || !output.runId)
5
+ return null;
6
+ const payload = output.suspendPayload;
7
+ if (typeof payload !== "object" || payload === null)
8
+ return null;
9
+ const { toolCallId, toolName, args } = payload;
10
+ // A tool that called suspend() is waiting on data, not on a decision.
11
+ if ("suspendPayload" in payload || typeof toolCallId !== "string")
12
+ return null;
13
+ return {
14
+ runId: output.runId,
15
+ toolCallId,
16
+ toolName: typeof toolName === "string" ? toolName : "a tool",
17
+ args: args ?? {},
18
+ };
19
+ }
20
+ /**
21
+ * Decide the call a suspended output is waiting on, and resume the run.
22
+ * Returns the resumed run's output, or null when nothing was waiting on a
23
+ * person.
24
+ */
25
+ export async function resolveMastraApproval(agent, output, options) {
26
+ const pending = pendingMastraApproval(output);
27
+ if (!pending)
28
+ return null;
29
+ const { runId, toolCallId, toolName, args } = pending;
30
+ if (options.when && !(await options.when(toolName, args))) {
31
+ return agent.approveToolCallGenerate({ runId, toolCallId });
32
+ }
33
+ const outcome = await askAboutCall(toolName, args, `mastra:${runId}:${toolCallId}`, options);
34
+ return outcome.allowed
35
+ ? agent.approveToolCallGenerate({ runId, toolCallId })
36
+ : agent.declineToolCallGenerate({ runId, toolCallId, reason: outcome.reason });
37
+ }
38
+ /**
39
+ * Resume a Mastra run until nothing is waiting on a person.
40
+ *
41
+ * `first` is the output of `agent.generate(…)`, or the promise of it. A cap
42
+ * on rounds stops an agent that keeps asking from waiting forever.
43
+ */
44
+ export async function generateWithDeliverdApprovals(agent, first, options) {
45
+ const maxRounds = options.maxRounds ?? 10;
46
+ let output = await first;
47
+ for (let round = 0; pendingMastraApproval(output); round++) {
48
+ if (round >= maxRounds) {
49
+ throw new Error(`The run was still waiting for approval after ${maxRounds} rounds; stopping rather than asking forever.`);
50
+ }
51
+ output = (await resolveMastraApproval(agent, output, options));
52
+ }
53
+ return output;
54
+ }
@@ -0,0 +1,79 @@
1
+ import { type ToolApprovalOptions } from "./shared.js";
2
+ /**
3
+ * Meta's Muse Spark, on the Meta Model API: a person approves the function
4
+ * calls a response asks for, and only the approved ones run.
5
+ *
6
+ * Muse Spark has no approval hook of its own. A response lists the calls the
7
+ * model wants made and your loop makes them, so the loop is where a person
8
+ * comes in. Hand the calls to Deliverd with the function that runs them:
9
+ *
10
+ * ```ts
11
+ * import OpenAI from "openai";
12
+ * import { Deliverd } from "@deliverd/sdk";
13
+ * import { runMuseFunctionCalls } from "@deliverd/sdk/adapters";
14
+ *
15
+ * const muse = new OpenAI({ baseURL: "https://api.meta.ai/v1", apiKey: process.env.MODEL_API_KEY });
16
+ * let resp = await muse.responses.create({ model: "muse-spark-1.1", input, tools });
17
+ * const results = await runMuseFunctionCalls(resp.output, runTool, {
18
+ * deliverd: new Deliverd(),
19
+ * when: (tool) => tool === "refund",
20
+ * approvers: ["finance"],
21
+ * });
22
+ * resp = await muse.responses.create({ model: "muse-spark-1.1", input: results, tools, previous_response_id: resp.id });
23
+ * ```
24
+ *
25
+ * `runMuseFunctionCalls` reads the Responses API's `function_call` items and
26
+ * returns its `function_call_output` items; `runMuseToolCalls` reads a Chat
27
+ * Completions message's `tool_calls` and returns `role: "tool"` messages.
28
+ * A declined call is not run: its result is a sentence telling the model a
29
+ * person said no, and why, so the model changes course instead of the run
30
+ * crashing. Both shapes are the OpenAI-compatible ones Meta's Model API
31
+ * serves, so they work for any endpoint that speaks them.
32
+ */
33
+ export interface MuseToolApprovalOptions extends ToolApprovalOptions {
34
+ /**
35
+ * Fields of a call's arguments the approver may correct before approving,
36
+ * per tool: `editable: (tool) => tool === "refund" ? ["amount"] : []`. The
37
+ * call then runs with what they approved rather than what the model asked.
38
+ */
39
+ editable?: (toolName: string, input: Record<string, unknown>) => string[];
40
+ }
41
+ /** Runs one call: the tool's name and its parsed arguments. A string result is passed on as it is; anything else as JSON. */
42
+ export type MuseToolRunner = (toolName: string, input: unknown) => unknown | Promise<unknown>;
43
+ /** A Responses API output item asking for a function call. */
44
+ export interface MuseFunctionCall {
45
+ type: "function_call";
46
+ call_id: string;
47
+ name: string;
48
+ arguments: string;
49
+ }
50
+ /** What goes back as the next request's `input`, one per call. */
51
+ export interface MuseFunctionCallOutput {
52
+ type: "function_call_output";
53
+ call_id: string;
54
+ output: string;
55
+ }
56
+ /** A Chat Completions tool call, from `choices[0].message.tool_calls`. */
57
+ export interface MuseToolCall {
58
+ id: string;
59
+ type?: string;
60
+ function: {
61
+ name: string;
62
+ arguments: string;
63
+ };
64
+ }
65
+ /** The `role: "tool"` message answering one tool call. */
66
+ export interface MuseToolMessage {
67
+ role: "tool";
68
+ tool_call_id: string;
69
+ content: string;
70
+ }
71
+ /** Ask about, and run, every `function_call` in a Responses API output. Other items are ignored. */
72
+ export declare function runMuseFunctionCalls(output: readonly {
73
+ type?: string;
74
+ }[], run: MuseToolRunner, options: MuseToolApprovalOptions): Promise<MuseFunctionCallOutput[]>;
75
+ /** Ask about, and run, every tool call on a Chat Completions message. */
76
+ export declare function runMuseToolCalls(message: {
77
+ tool_calls?: readonly MuseToolCall[] | null;
78
+ }, run: MuseToolRunner, options: MuseToolApprovalOptions): Promise<MuseToolMessage[]>;
79
+ //# sourceMappingURL=muse-spark.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"muse-spark.d.ts","sourceRoot":"","sources":["../../src/adapters/muse-spark.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;CAC3E;AAED,6HAA6H;AAC7H,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9F,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oGAAoG;AACpG,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,EACpC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAYnC;AAED,yEAAyE;AACzE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAAA;CAAE,EACxD,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,EAAE,CAAC,CAU5B"}
@@ -0,0 +1,59 @@
1
+ import { askAboutCall } from "./shared.js";
2
+ /** Ask about, and run, every `function_call` in a Responses API output. Other items are ignored. */
3
+ export async function runMuseFunctionCalls(output, run, options) {
4
+ const results = [];
5
+ for (const item of output) {
6
+ if (item.type !== "function_call")
7
+ continue;
8
+ const call = item;
9
+ results.push({
10
+ type: "function_call_output",
11
+ call_id: call.call_id,
12
+ output: await approveAndRun(call.name, call.arguments, call.call_id, run, options),
13
+ });
14
+ }
15
+ return results;
16
+ }
17
+ /** Ask about, and run, every tool call on a Chat Completions message. */
18
+ export async function runMuseToolCalls(message, run, options) {
19
+ const results = [];
20
+ for (const call of message.tool_calls ?? []) {
21
+ results.push({
22
+ role: "tool",
23
+ tool_call_id: call.id,
24
+ content: await approveAndRun(call.function.name, call.function.arguments, call.id, run, options),
25
+ });
26
+ }
27
+ return results;
28
+ }
29
+ async function approveAndRun(toolName, rawArguments, callId, run, options) {
30
+ const input = parseArguments(rawArguments);
31
+ if (!options.when || (await options.when(toolName, input))) {
32
+ const editable = typeof input === "object" && input !== null && !Array.isArray(input)
33
+ ? options.editable?.(toolName, input)
34
+ : undefined;
35
+ // The call id makes the ask idempotent: a loop that is retried, or a
36
+ // process restarted mid-wait, finds the request it already made.
37
+ const outcome = await askAboutCall(toolName, input, `muse-spark:${callId}`, options, undefined, editable);
38
+ if (!outcome.allowed)
39
+ return outcome.reason;
40
+ // What was approved runs, which is the proposal unless a person corrected it.
41
+ return render(await run(toolName, outcome.input ?? input));
42
+ }
43
+ return render(await run(toolName, input));
44
+ }
45
+ function render(result) {
46
+ if (typeof result === "string")
47
+ return result;
48
+ return JSON.stringify(result ?? null);
49
+ }
50
+ function parseArguments(raw) {
51
+ if (!raw)
52
+ return {};
53
+ try {
54
+ return JSON.parse(raw);
55
+ }
56
+ catch {
57
+ return raw;
58
+ }
59
+ }
@@ -6,7 +6,8 @@ import type { ApprovalFactor, ApprovalRisk, Decision, FieldChange } from "../typ
6
6
  *
7
7
  * The adapters are written against each framework's own hook — the Claude
8
8
  * Agent SDK's `canUseTool`, the AI SDK's `toolApproval`, the OpenAI Agents
9
- * SDK's interruptions, LangGraph's `interrupt` — by shape rather than by
9
+ * SDK's interruptions, LangGraph's `interrupt`, Mastra's suspended tool
10
+ * approvals, the function calls in a Muse Spark response — by shape rather than by
10
11
  * import, so `@deliverd/sdk` keeps its promise of no dependencies. Each
11
12
  * shape was taken from that framework's published type definitions and is
12
13
  * checked against them in this package's tests.
@@ -1 +1 @@
1
- {"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;;;GAWG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,OAAO,EAAE;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,YAAY,CAAC;QACpB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,SAAS,CAAC,EAAE,QAAQ,CAAC;QACrB,OAAO,CAAC,EAAE,QAAQ,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC;IACjE,8EAA8E;IAC9E,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAQD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOnF;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAe,CAAC;AAGlD,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,eAAe,CAapF;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GACnB;IACE,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB,GACD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW;AACpB,uFAAuF;AACvF,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC,WAAW,CAAC,CAmCtB;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,MAAM,CAWjH"}
@@ -0,0 +1,233 @@
1
+ /**
2
+ * Screening what an agent is about to send to an AI model.
3
+ *
4
+ * Before a prompt, a document or a retrieved record goes to a model, this
5
+ * finds the personal data, secrets and confidential terms in it, says how
6
+ * sensitive the whole is, and decides — against what the organisation has
7
+ * approved that model to receive — whether it may go as it is, go with the
8
+ * findings replaced by placeholders, go only once a person agrees, or not go.
9
+ *
10
+ * Three lines are held throughout:
11
+ *
12
+ * - **The text need not leave the caller.** Everything here is pure and has no
13
+ * imports, so the SDKs run the same detectors where the agent runs and send
14
+ * Deliverd only counts: "two email addresses, one IBAN". This file is copied
15
+ * verbatim into `packages/sdk/src/data-screen.ts` and into the open-source
16
+ * `packages/screen/src/data-screen.ts`, and a test fails when they differ.
17
+ * - **A finding never carries its value off the machine.** `ScreenFinding` has
18
+ * offsets into the caller's own text; `summarise` keeps only counts.
19
+ * - **Detection is a net, not a guarantee.** Patterns find structured
20
+ * identifiers well and names hardly at all; a name is personal data and
21
+ * nothing here claims to have found every one. Pseudonymised text is still
22
+ * personal data in law. What this buys is fewer identifiers sent, a record of
23
+ * what was, and a person asked when it matters — never a certificate that a
24
+ * prompt is clean.
25
+ */
26
+ /** Ordered: the stricter of two classifications is the later one. */
27
+ export declare const SCREEN_CLASSIFICATIONS: readonly ["public", "internal", "confidential", "restricted"];
28
+ export type ScreenClassification = (typeof SCREEN_CLASSIFICATIONS)[number];
29
+ export declare const SCREEN_CATEGORIES: readonly ["personal", "financial", "special", "secret", "confidential"];
30
+ export type ScreenCategory = (typeof SCREEN_CATEGORIES)[number];
31
+ export declare const SCREEN_VERDICTS: readonly ["allow", "redact", "ask", "deny"];
32
+ export type ScreenVerdict = (typeof SCREEN_VERDICTS)[number];
33
+ /** What a policy may do with data the target is not approved for. */
34
+ export type ScreenAction = "redact" | "ask" | "deny";
35
+ export declare const DATA_KINDS: {
36
+ readonly email: {
37
+ readonly label: "Email address";
38
+ readonly category: "personal";
39
+ readonly placeholder: "EMAIL";
40
+ readonly redactable: true;
41
+ };
42
+ readonly phone: {
43
+ readonly label: "Phone number";
44
+ readonly category: "personal";
45
+ readonly placeholder: "PHONE";
46
+ readonly redactable: true;
47
+ };
48
+ readonly iban: {
49
+ readonly label: "IBAN";
50
+ readonly category: "financial";
51
+ readonly placeholder: "IBAN";
52
+ readonly redactable: true;
53
+ };
54
+ readonly payment_card: {
55
+ readonly label: "Payment card number";
56
+ readonly category: "financial";
57
+ readonly placeholder: "CARD";
58
+ readonly redactable: true;
59
+ };
60
+ readonly uk_national_insurance: {
61
+ readonly label: "UK National Insurance number";
62
+ readonly category: "personal";
63
+ readonly placeholder: "NINO";
64
+ readonly redactable: true;
65
+ };
66
+ readonly ie_pps: {
67
+ readonly label: "Irish PPS number";
68
+ readonly category: "personal";
69
+ readonly placeholder: "PPS";
70
+ readonly redactable: true;
71
+ };
72
+ readonly us_ssn: {
73
+ readonly label: "US Social Security number";
74
+ readonly category: "personal";
75
+ readonly placeholder: "SSN";
76
+ readonly redactable: true;
77
+ };
78
+ readonly ip_address: {
79
+ readonly label: "IP address";
80
+ readonly category: "personal";
81
+ readonly placeholder: "IP";
82
+ readonly redactable: true;
83
+ };
84
+ readonly date_of_birth: {
85
+ readonly label: "Date of birth";
86
+ readonly category: "personal";
87
+ readonly placeholder: "DOB";
88
+ readonly redactable: true;
89
+ };
90
+ /** Never found by a pattern here: only by a model detector the caller plugs in (`spans`). */
91
+ readonly person_name: {
92
+ readonly label: "Person's name";
93
+ readonly category: "personal";
94
+ readonly placeholder: "NAME";
95
+ readonly redactable: true;
96
+ };
97
+ readonly special_category: {
98
+ readonly label: "Special-category data";
99
+ readonly category: "special";
100
+ readonly placeholder: "SPECIAL";
101
+ readonly redactable: false;
102
+ };
103
+ readonly secret: {
104
+ readonly label: "Secret or credential";
105
+ readonly category: "secret";
106
+ readonly placeholder: "SECRET";
107
+ readonly redactable: true;
108
+ };
109
+ readonly term: {
110
+ readonly label: "Confidential term";
111
+ readonly category: "confidential";
112
+ readonly placeholder: "TERM";
113
+ readonly redactable: true;
114
+ };
115
+ };
116
+ export type DataKind = keyof typeof DATA_KINDS;
117
+ export declare const DATA_KIND_KEYS: DataKind[];
118
+ /**
119
+ * A word or phrase the organisation does not want sent: a client's name, a
120
+ * project's code name, a deal. Matched whole-word and case-insensitively.
121
+ */
122
+ export interface ScreenTerm {
123
+ term: string;
124
+ /** Shown to people and used in the placeholder: `[CLIENT_1]`. */
125
+ label?: string;
126
+ classification?: "confidential" | "restricted";
127
+ }
128
+ export interface ScreenFinding {
129
+ kind: DataKind;
130
+ category: ScreenCategory;
131
+ classification: ScreenClassification;
132
+ /** Offsets into the screened text. The value itself is never copied. */
133
+ start: number;
134
+ end: number;
135
+ /** For a term, its label; otherwise the kind's. */
136
+ label: string;
137
+ redactable: boolean;
138
+ }
139
+ export type ScreenCounts = Partial<Record<DataKind, number>>;
140
+ /** Terms past this are ignored, so a pasted list cannot make every screen slow. */
141
+ export declare const MAX_SCREEN_TERMS = 500;
142
+ /**
143
+ * What another detector found — a named-entity model, a DLP service — handed
144
+ * in as offsets into the same text. Patterns cannot find names; a model can,
145
+ * and this is where its answer joins theirs.
146
+ */
147
+ export interface DetectedSpan {
148
+ kind: DataKind;
149
+ start: number;
150
+ end: number;
151
+ }
152
+ /**
153
+ * A detector to run beside the patterns: a function from the text to its
154
+ * spans. The open-source `@deliverd/screen` package has adapters that turn a
155
+ * Hugging Face token classifier or a Presidio analyzer into one.
156
+ */
157
+ export type SpanDetector = (text: string) => readonly DetectedSpan[] | Promise<readonly DetectedSpan[]>;
158
+ /**
159
+ * Find what is in a text. Overlapping matches keep the stronger kind, so each
160
+ * character belongs to at most one finding. `spans` are another detector's
161
+ * findings, held to the same rules; one outside the text or of no known kind
162
+ * is dropped.
163
+ */
164
+ export declare function screenText(text: string, terms?: readonly ScreenTerm[], spans?: readonly DetectedSpan[]): ScreenFinding[];
165
+ /** Counts only: what goes over the wire when the text stays where it is. */
166
+ export declare function summarise(findings: readonly ScreenFinding[]): ScreenCounts;
167
+ export interface Redaction {
168
+ text: string;
169
+ /** Placeholder to original value. Stays with the caller; never sent anywhere. */
170
+ replacements: Record<string, string>;
171
+ }
172
+ /**
173
+ * Replace each redactable finding with a placeholder. The same value gets the
174
+ * same placeholder throughout, so a model can still tell that two mentions are
175
+ * one person, and `restore` can put the values back in its answer.
176
+ */
177
+ export declare function redact(text: string, findings: readonly ScreenFinding[]): Redaction;
178
+ /** Put the original values back into text a model wrote using the placeholders. */
179
+ export declare function restore(text: string, replacements: Readonly<Record<string, string>>): string;
180
+ /** What the destination model is approved to receive: the AI register's record. */
181
+ export interface ScreenTarget {
182
+ name: string;
183
+ /** The highest classification approved; null when the record does not say. */
184
+ approvedClassification: ScreenClassification | null;
185
+ personalData: boolean;
186
+ active: boolean;
187
+ }
188
+ export interface ScreenPolicy {
189
+ /** Secrets and credentials. Default deny: a key sent to a model is a key disclosed. */
190
+ secrets: ScreenAction;
191
+ /** Redactable data the target is not approved for. Default redact. */
192
+ beyondApproval: ScreenAction;
193
+ /** Data that redaction cannot fix (special category) the target is not approved for. Default ask. */
194
+ notRedactable: "ask" | "deny";
195
+ /** What an unnamed target is taken to be approved for. Default internal, no personal data. */
196
+ unregistered: {
197
+ approvedClassification: ScreenClassification;
198
+ personalData: boolean;
199
+ };
200
+ }
201
+ export declare const DEFAULT_SCREEN_POLICY: ScreenPolicy;
202
+ export interface ScreenAssessment {
203
+ verdict: ScreenVerdict;
204
+ /** The classification of what was found; public when nothing was. */
205
+ classification: ScreenClassification;
206
+ personalData: boolean;
207
+ categories: ScreenCategory[];
208
+ /** The kinds behind the verdict: what redaction replaces, and what a person is asked about. */
209
+ offending: DataKind[];
210
+ /** One sentence each, for the agent and for the person asked. */
211
+ reasons: string[];
212
+ }
213
+ /** Reads a stored or sent policy, keeping a default for anything missing or unknown. */
214
+ export declare function readScreenPolicy(raw: unknown): ScreenPolicy;
215
+ /** "2 email addresses and 1 IBAN", for a reason or an approval's title. */
216
+ export declare function describeCounts(counts: ScreenCounts): string;
217
+ /**
218
+ * Decide from counts alone, so the same answer comes back whether the text was
219
+ * screened here or on the caller's machine.
220
+ *
221
+ * `termClassification` is the strictest classification among the terms found,
222
+ * which counts cannot carry; restricted when a caller says so.
223
+ */
224
+ export declare function assessCounts(counts: ScreenCounts, target: ScreenTarget | null, policy?: ScreenPolicy, termClassification?: ScreenClassification): ScreenAssessment;
225
+ /**
226
+ * The text with the findings behind a verdict replaced: only those, so data
227
+ * the target is approved for still reaches it. What a person asked is shown,
228
+ * and what a `redact` verdict sends. Null for a deny, which sends nothing.
229
+ */
230
+ export declare function redactFor(text: string, findings: readonly ScreenFinding[], assessment: Pick<ScreenAssessment, "verdict" | "offending">): Redaction | null;
231
+ /** The strictest classification among the terms found, for `assessCounts`. */
232
+ export declare function termClassificationOf(findings: readonly ScreenFinding[]): ScreenClassification;
233
+ //# sourceMappingURL=data-screen.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"data-screen.d.ts","sourceRoot":"","sources":["../src/data-screen.ts"],"names":[],"mappings":"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"}