@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/src/screen.ts ADDED
@@ -0,0 +1,144 @@
1
+ import type { Approval, Approvals } from "./approvals.js";
2
+ import {
3
+ redactFor,
4
+ restore,
5
+ screenText,
6
+ summarise,
7
+ termClassificationOf,
8
+ type DataKind,
9
+ type DetectedSpan,
10
+ type ScreenTerm,
11
+ type SpanDetector,
12
+ } from "./data-screen.js";
13
+ import { durationMs, type Duration } from "./duration.js";
14
+ import type { HttpClient } from "./http.js";
15
+ import type { ScreenData, ScreenVerdict } from "./types.js";
16
+
17
+ /**
18
+ * Check text before it goes to an AI model.
19
+ *
20
+ * ```ts
21
+ * const screened = await deliverd.screen(prompt, { aiSystemId: CLAIMS_MODEL });
22
+ * if (!screened.allowed) return screened.reasons;
23
+ * const answer = await model.generate(screened.text);
24
+ * return screened.restore(answer);
25
+ * ```
26
+ *
27
+ * **The text does not leave your machine.** The detectors run here — the same
28
+ * code the server runs — and Deliverd is sent only what was found, by kind:
29
+ * "two email addresses, one IBAN". It answers from what the organisation's AI
30
+ * register approves that model to receive, and from its policy:
31
+ *
32
+ * - `allow`: send it as it is.
33
+ * - `redact`: `screened.text` has the findings replaced by placeholders such
34
+ * as `[EMAIL_1]`; send that, and `restore()` puts the values back in the
35
+ * model's answer.
36
+ * - `ask`: a person decides, through an ordinary approval, and this waits for
37
+ * them. Approved, `screened.text` is the original.
38
+ * - `deny`: nothing may be sent. `screened.text` is null.
39
+ *
40
+ * **A net, not a guarantee.** Structured identifiers are found well; names
41
+ * are not found reliably. Never tell anyone a text is clean because this
42
+ * allowed it.
43
+ */
44
+
45
+ export interface ScreenOptions {
46
+ /** The AI register's record for the model it is going to. Without one, it is held to internal data and no personal data. */
47
+ aiSystemId?: string;
48
+ /** What it is for, shown to a person if one is asked. */
49
+ purpose?: string;
50
+ /** Your own reference, kept on any approval. */
51
+ externalId?: string;
52
+ /**
53
+ * Words your organisation does not want sent — clients, code names — found
54
+ * here like any other kind. Terms an administrator set in Deliverd are
55
+ * applied only to text the server reads, so pass yours here.
56
+ */
57
+ terms?: readonly ScreenTerm[];
58
+ /**
59
+ * Detectors to run here beside the patterns, such as a named-entity model
60
+ * for people's names, which patterns cannot find. Each gets the text and
61
+ * returns spans; `@deliverd/screen` has adapters for Hugging Face and
62
+ * Presidio. They run on your machine, like the patterns, and only their
63
+ * counts are sent.
64
+ */
65
+ detectors?: readonly SpanDetector[];
66
+ /** Spans another detector already found in this text. */
67
+ spans?: readonly DetectedSpan[];
68
+ /** Whether to wait for a person on an `ask`. Default true. */
69
+ wait?: boolean;
70
+ timeout?: Duration;
71
+ signal?: AbortSignal;
72
+ }
73
+
74
+ export class Screened {
75
+ /** The approval a person decided, for an `ask`. */
76
+ readonly approval: Approval | null;
77
+
78
+ constructor(
79
+ /** What the server answered. */
80
+ readonly data: ScreenData,
81
+ /** What may be sent: the original, the redacted text, or null when nothing may be. */
82
+ readonly text: string | null,
83
+ /** Whether to send `text`. False for a deny, and for an ask a person did not approve. */
84
+ readonly allowed: boolean,
85
+ private readonly replacements: Readonly<Record<string, string>>,
86
+ approval: Approval | null = null
87
+ ) {
88
+ this.approval = approval;
89
+ }
90
+
91
+ get verdict(): ScreenVerdict {
92
+ return this.data.verdict;
93
+ }
94
+
95
+ /** One sentence each: why, for logging or for telling the person. */
96
+ get reasons(): string[] {
97
+ return this.data.reasons;
98
+ }
99
+
100
+ /** Put the original values back into text a model wrote using the placeholders. */
101
+ restore(answer: string): string {
102
+ return restore(answer, this.replacements);
103
+ }
104
+ }
105
+
106
+ export async function screen(
107
+ http: HttpClient,
108
+ approvals: Approvals,
109
+ text: string,
110
+ options: ScreenOptions = {},
111
+ development = false
112
+ ): Promise<Screened> {
113
+ const spans = [...(options.spans ?? [])];
114
+ for (const detect of options.detectors ?? []) spans.push(...(await detect(text)));
115
+ const findings = screenText(text, options.terms ?? [], spans);
116
+ const data = await http.request<ScreenData>({
117
+ method: "POST",
118
+ path: "/screen",
119
+ body: {
120
+ counts: summarise(findings),
121
+ termClassification: termClassificationOf(findings),
122
+ ...(options.aiSystemId ? { aiSystemId: options.aiSystemId } : {}),
123
+ ...(options.purpose ? { purpose: options.purpose } : {}),
124
+ ...(options.externalId ? { externalId: options.externalId } : {}),
125
+ },
126
+ signal: options.signal,
127
+ });
128
+
129
+ if (data.verdict === "allow") return new Screened(data, text, true, {});
130
+ if (data.verdict === "deny") return new Screened(data, null, false, {});
131
+ if (data.verdict === "redact") {
132
+ const redacted = redactFor(text, findings, { verdict: data.verdict, offending: data.offending as DataKind[] });
133
+ return new Screened(data, redacted?.text ?? null, true, redacted?.replacements ?? {});
134
+ }
135
+
136
+ // ask
137
+ if (!data.approval || options.wait === false) return new Screened(data, null, false, {});
138
+ const approval = await approvals.get(data.approval.id, options.signal);
139
+ const settled = await approval.wait({
140
+ signal: options.signal,
141
+ timeout: options.timeout === undefined ? (development ? 2_000 : undefined) : durationMs(options.timeout),
142
+ });
143
+ return settled.approved ? new Screened(data, text, true, {}, settled) : new Screened(data, null, false, {}, settled);
144
+ }
package/src/tasks.ts CHANGED
@@ -6,13 +6,18 @@ import type {
6
6
  ApplySideTaskInput,
7
7
  CancelTaskInput,
8
8
  CompleteTaskInput,
9
+ ControlApprovalInput,
10
+ ControlApprovalResult,
9
11
  CreateSideTaskInput,
10
12
  CreateTaskInput,
11
13
  DecisionApproval,
12
14
  Governance,
13
15
  GovernanceGateCheck,
16
+ GovernancePack,
17
+ GovernanceProfileInput,
14
18
  LinkTasksInput,
15
19
  ListTasksInput,
20
+ ReassessmentResult,
16
21
  RequestDecisionApprovalInput,
17
22
  SubmitEvidenceInput,
18
23
  TaskContext,
@@ -20,6 +25,7 @@ import type {
20
25
  TaskFinding,
21
26
  TaskGraph,
22
27
  TaskLinkResult,
28
+ UpdateGovernanceProfileInput,
23
29
  UpdateTaskInput,
24
30
  } from "./types.js";
25
31
 
@@ -219,6 +225,31 @@ export class Task {
219
225
  checkGovernanceGate(options: { action?: string } = {}, signal?: AbortSignal): Promise<GovernanceGateCheck> {
220
226
  return new Tasks(this.http).checkGovernanceGate(this.data.id, options, signal);
221
227
  }
228
+
229
+ /** Govern it (Compliance Mode). Already governed, it answers with the governance it has. */
230
+ govern(profile: GovernanceProfileInput = {}, signal?: AbortSignal): Promise<Governance> {
231
+ return new Tasks(this.http).govern(this.data.id, profile, signal);
232
+ }
233
+
234
+ /** Change its governance profile. An agent may raise risk or add facts; only a person lowers or clears them. */
235
+ updateGovernanceProfile(input: UpdateGovernanceProfileInput, signal?: AbortSignal): Promise<Governance> {
236
+ return new Tasks(this.http).updateGovernanceProfile(this.data.id, input, signal);
237
+ }
238
+
239
+ /** Put an approval control to a person through the organisation's approval process. */
240
+ requestControlApproval(control: string, input: ControlApprovalInput = {}, signal?: AbortSignal): Promise<ControlApprovalResult> {
241
+ return new Tasks(this.http).requestControlApproval(this.data.id, control, input, signal);
242
+ }
243
+
244
+ /** Ask for it to be reassessed (Enterprise). The governance gate stays closed until a person completes it. */
245
+ triggerReassessment(reason: string, signal?: AbortSignal): Promise<ReassessmentResult> {
246
+ return new Tasks(this.http).triggerReassessment(this.data.id, reason, signal);
247
+ }
248
+
249
+ /** Its evidence pack, with a digest. It assists audit; it does not certify compliance. */
250
+ evidencePack(signal?: AbortSignal): Promise<GovernancePack> {
251
+ return new Tasks(this.http).evidencePack(this.data.id, signal);
252
+ }
222
253
  }
223
254
 
224
255
  export class Tasks {
@@ -364,4 +395,61 @@ export class Tasks {
364
395
  signal,
365
396
  });
366
397
  }
398
+
399
+ /**
400
+ * Govern an objective (Compliance Mode, Business and Enterprise): the AI
401
+ * system, purpose, owners, risk, data and oversight, as far as they are
402
+ * known. Idempotent: an objective already governed answers with its
403
+ * governance. A side task's id answers for its objective.
404
+ */
405
+ govern(id: string, profile: GovernanceProfileInput = {}, signal?: AbortSignal): Promise<Governance> {
406
+ return this.http.request<Governance>({ method: "POST", path: `/tasks/${enc(id)}/governance`, body: profile, signal });
407
+ }
408
+
409
+ /**
410
+ * Change a governed task's profile. An agent may raise risk or add facts;
411
+ * only a person lowers or clears them. With `expectedVersion`, refused if
412
+ * somebody wrote in between.
413
+ */
414
+ updateGovernanceProfile(id: string, input: UpdateGovernanceProfileInput, signal?: AbortSignal): Promise<Governance> {
415
+ return this.http.request<Governance>({ method: "PATCH", path: `/tasks/${enc(id)}/governance`, body: input, signal });
416
+ }
417
+
418
+ /**
419
+ * Put an approval control (a compliance or deployment approval) to a person
420
+ * through the organisation's approval process. The control is satisfied
421
+ * when that approval is approved. Needs `approvals:write`.
422
+ */
423
+ requestControlApproval(
424
+ id: string,
425
+ control: string,
426
+ input: ControlApprovalInput = {},
427
+ signal?: AbortSignal
428
+ ): Promise<ControlApprovalResult> {
429
+ return this.http.request<ControlApprovalResult>({
430
+ method: "POST",
431
+ path: `/tasks/${enc(id)}/governance/controls/${enc(control)}/approval`,
432
+ body: input,
433
+ signal,
434
+ });
435
+ }
436
+
437
+ /** Ask for a governed task to be reassessed (Enterprise). Its governance gate stays closed until a person completes it. */
438
+ triggerReassessment(id: string, reason: string, signal?: AbortSignal): Promise<ReassessmentResult> {
439
+ return this.http.request<ReassessmentResult>({
440
+ method: "POST",
441
+ path: `/tasks/${enc(id)}/governance/reassessments`,
442
+ body: { reason },
443
+ signal,
444
+ });
445
+ }
446
+
447
+ /**
448
+ * A governed task's evidence pack: profile, controls, evidence, task graph,
449
+ * decisions, approvals and the audit timeline, with a digest. It assists
450
+ * audit; it does not certify compliance. Every export is audited.
451
+ */
452
+ evidencePack(id: string, signal?: AbortSignal): Promise<GovernancePack> {
453
+ return this.http.request<GovernancePack>({ method: "GET", path: `/tasks/${enc(id)}/governance/pack`, signal });
454
+ }
367
455
  }