@deliverd/sdk 0.27.0 → 0.29.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/src/screen.ts CHANGED
@@ -12,6 +12,7 @@ import {
12
12
  } from "./data-screen.js";
13
13
  import { durationMs, type Duration } from "./duration.js";
14
14
  import type { HttpClient } from "./http.js";
15
+ import type { PurviewCheck } from "./purview.js";
15
16
  import type { ScreenData, ScreenVerdict } from "./types.js";
16
17
 
17
18
  /**
@@ -65,6 +66,13 @@ export interface ScreenOptions {
65
66
  detectors?: readonly SpanDetector[];
66
67
  /** Spans another detector already found in this text. */
67
68
  spans?: readonly DetectedSpan[];
69
+ /**
70
+ * Your organisation's Microsoft Purview, asked about the text before
71
+ * Deliverd: build one with `purviewCheck()`. The text goes from here to
72
+ * Microsoft, never to Deliverd, and only Purview's answer is sent on. A
73
+ * Purview block stops the text; a warn puts it to a person.
74
+ */
75
+ purview?: PurviewCheck;
68
76
  /** Whether to wait for a person on an `ask`. Default true. */
69
77
  wait?: boolean;
70
78
  timeout?: Duration;
@@ -113,6 +121,7 @@ export async function screen(
113
121
  const spans = [...(options.spans ?? [])];
114
122
  for (const detect of options.detectors ?? []) spans.push(...(await detect(text)));
115
123
  const findings = screenText(text, options.terms ?? [], spans);
124
+ const purview = options.purview ? await options.purview(text) : null;
116
125
  const data = await http.request<ScreenData>({
117
126
  method: "POST",
118
127
  path: "/screen",
@@ -122,6 +131,7 @@ export async function screen(
122
131
  ...(options.aiSystemId ? { aiSystemId: options.aiSystemId } : {}),
123
132
  ...(options.purpose ? { purpose: options.purpose } : {}),
124
133
  ...(options.externalId ? { externalId: options.externalId } : {}),
134
+ ...(purview ? { purview } : {}),
125
135
  },
126
136
  signal: options.signal,
127
137
  });
package/src/types.ts CHANGED
@@ -1500,10 +1500,38 @@ export interface TaskContext {
1500
1500
  * `reports.update()` rather than publishing a second on the same thing.
1501
1501
  */
1502
1502
  reports: TaskContextReport[];
1503
+ /**
1504
+ * Confirmed knowledge for this task, few and cut short: what its playbook
1505
+ * and step name first, then the most relevant. A person confirmed each one;
1506
+ * propose anything new with `knowledge.propose()`.
1507
+ */
1508
+ knowledge: TaskContextKnowledge[];
1509
+ /** The playbook this run follows, and this task's step in it; null when none. */
1510
+ playbook: TaskContextPlaybook | null;
1503
1511
  /** One paragraph to say back to yourself to re-anchor on the objective. */
1504
1512
  reanchor: string;
1505
1513
  }
1506
1514
 
1515
+ /** A confirmed knowledge entry, as a task's context gives it. */
1516
+ export interface TaskContextKnowledge {
1517
+ id: string;
1518
+ kind: KnowledgeKind;
1519
+ title: string;
1520
+ /** Cut at 600 characters; `knowledge.get(id)` has the rest. */
1521
+ body: string;
1522
+ confirmedBy: string | null;
1523
+ url: string;
1524
+ }
1525
+
1526
+ /** The playbook a task follows, and its step. */
1527
+ export interface TaskContextPlaybook {
1528
+ id: string;
1529
+ title: string;
1530
+ version: number;
1531
+ /** The step this task is, with the call its rule needs before acting; null on the objective itself. */
1532
+ step: { key: string; title: string; rule: PlaybookStepRule; action: string | null; call: string | null } | null;
1533
+ }
1534
+
1507
1535
  /** A report published for a task, as its context names it. */
1508
1536
  export interface TaskContextReport {
1509
1537
  id: string;
@@ -2593,6 +2621,16 @@ export interface ScreenApprovalRef {
2593
2621
  status: string;
2594
2622
  }
2595
2623
 
2624
+ /** Microsoft Purview's answer, as the caller sent it. Never the text. */
2625
+ export interface ScreenPurviewData {
2626
+ /** `null` when Purview returned no restriction. */
2627
+ restriction: "audit" | "warn" | "block" | null;
2628
+ actions: number;
2629
+ scopeModified: boolean;
2630
+ /** Purview could not be reached; `restriction` is what the caller chose for that case. */
2631
+ unavailable: boolean;
2632
+ }
2633
+
2596
2634
  /** What `POST /screen` answers: the verdict, and why. */
2597
2635
  export interface ScreenData {
2598
2636
  verdict: ScreenVerdict;
@@ -2612,4 +2650,324 @@ export interface ScreenData {
2612
2650
  redactedText: string | null;
2613
2651
  /** The approval a person decides, for an `ask` verdict. */
2614
2652
  approval: ScreenApprovalRef | null;
2653
+ /** Microsoft Purview's answer, when `screen()` was given a `purview` check. */
2654
+ purview?: ScreenPurviewData | null;
2655
+ }
2656
+
2657
+ // ── Context: knowledge and playbooks ────────────────────────────────────────
2658
+
2659
+ export type KnowledgeKind = "fact" | "convention" | "decision" | "procedure" | "glossary" | "contact" | "known_issue";
2660
+ export type KnowledgeStatus = "proposed" | "confirmed" | "rejected" | "retired" | "superseded";
2661
+ /** `open` is proposed and confirmed together. */
2662
+ export type KnowledgeStatusFilter = KnowledgeStatus | "open" | "all";
2663
+
2664
+ /** Where an entry came from. */
2665
+ export interface KnowledgeSource {
2666
+ kind: "manual" | "finding" | "decision" | "import" | "url" | "agent";
2667
+ id?: string;
2668
+ url?: string;
2669
+ label?: string;
2670
+ }
2671
+
2672
+ /** One entry of the organisation's knowledge. Only `confirmed` is to be relied on. */
2673
+ export interface KnowledgeEntryData {
2674
+ id: string;
2675
+ url: string;
2676
+ kind: KnowledgeKind;
2677
+ kindLabel: string;
2678
+ title: string;
2679
+ body: string;
2680
+ tags: string[];
2681
+ status: KnowledgeStatus;
2682
+ workspaceId: string | null;
2683
+ flowId: string | null;
2684
+ /** The confirmed entry this replaces once it is confirmed. */
2685
+ supersedesId: string | null;
2686
+ supersededById: string | null;
2687
+ source: KnowledgeSource;
2688
+ owner: string | null;
2689
+ reviewDueOn: string | null;
2690
+ reviewOverdue: boolean;
2691
+ lastReviewedAt: string | null;
2692
+ confirmedBy: string | null;
2693
+ confirmedAt: string | null;
2694
+ decisionNote: string | null;
2695
+ retiredAt: string | null;
2696
+ retiredReason: string | null;
2697
+ externalId: string | null;
2698
+ proposedBy: string;
2699
+ createdAt: string;
2700
+ updatedAt: string;
2701
+ }
2702
+
2703
+ export interface KnowledgeDetail extends KnowledgeEntryData {
2704
+ /** Earlier versions this replaced and later ones that replaced it, oldest first. */
2705
+ history: { id: string; title: string; status: KnowledgeStatus; confirmedAt: string | null; url: string }[];
2706
+ /** A proposed revision waiting for a person, on a confirmed entry. */
2707
+ pendingRevision: { id: string; title: string; url: string } | null;
2708
+ }
2709
+
2710
+ export interface ProposeKnowledgeInput {
2711
+ kind: KnowledgeKind;
2712
+ /** The fact or rule in one line. */
2713
+ title: string;
2714
+ /** The detail another agent needs to act on it. A secret is refused. */
2715
+ body: string;
2716
+ tags?: string[];
2717
+ /** One workspace only; the whole organisation when omitted. */
2718
+ workspaceId?: string;
2719
+ flowId?: string;
2720
+ /** The confirmed entry this would replace, once a person confirms it. */
2721
+ supersedesId?: string;
2722
+ sourceUrl?: string;
2723
+ sourceLabel?: string;
2724
+ /** Your own reference. An open entry with the same one comes back instead of a second. */
2725
+ externalId?: string;
2726
+ }
2727
+
2728
+ export interface ProposedKnowledge {
2729
+ entry: KnowledgeEntryData;
2730
+ resumed: boolean;
2731
+ /** Personal data seen in what you wrote, said back to you; null when none. */
2732
+ screening: string | null;
2733
+ }
2734
+
2735
+ export interface EditKnowledgeInput {
2736
+ kind?: KnowledgeKind;
2737
+ title?: string;
2738
+ body?: string;
2739
+ tags?: string[];
2740
+ }
2741
+
2742
+ export interface SearchKnowledgeInput {
2743
+ /** Words, ranked by relevance. Omit for the newest. */
2744
+ q?: string;
2745
+ kind?: KnowledgeKind;
2746
+ /** `confirmed` when omitted. */
2747
+ status?: KnowledgeStatusFilter;
2748
+ workspaceId?: string;
2749
+ flowId?: string;
2750
+ limit?: number;
2751
+ }
2752
+
2753
+ export interface KnowledgeSearchResult {
2754
+ entries: KnowledgeEntryData[];
2755
+ /** True when the list was cut at the limit. */
2756
+ more: boolean;
2757
+ }
2758
+
2759
+ export interface PromoteFindingInput {
2760
+ kind?: KnowledgeKind;
2761
+ title?: string;
2762
+ body?: string;
2763
+ tags?: string[];
2764
+ }
2765
+
2766
+ export interface ImportKnowledgeInput {
2767
+ /** A Deliverd export, or a notes file such as AGENTS.md. Each heading becomes one proposed entry. */
2768
+ markdown: string;
2769
+ workspaceId?: string;
2770
+ /** Where the file came from, e.g. the repository and path. */
2771
+ source?: string;
2772
+ }
2773
+
2774
+ export interface ImportedKnowledge {
2775
+ created: KnowledgeEntryData[];
2776
+ skipped: { title: string; reason: string }[];
2777
+ }
2778
+
2779
+ export interface ExportKnowledgeInput {
2780
+ /** `confirmed` when omitted. */
2781
+ status?: KnowledgeStatusFilter;
2782
+ workspaceId?: string;
2783
+ }
2784
+
2785
+ /** A JSON export: portable entries, with their scope named rather than numbered. */
2786
+ export interface KnowledgeExport {
2787
+ format: "deliverd-knowledge";
2788
+ version: 1;
2789
+ organisation: string;
2790
+ exportedAt: string;
2791
+ entries: {
2792
+ id?: string;
2793
+ kind: KnowledgeKind;
2794
+ title: string;
2795
+ body: string;
2796
+ tags: string[];
2797
+ status?: KnowledgeStatus;
2798
+ /** The workspace's name, or Organisation. */
2799
+ scope?: string | null;
2800
+ owner?: string | null;
2801
+ confirmedBy?: string | null;
2802
+ confirmedOn?: string | null;
2803
+ reviewDueOn?: string | null;
2804
+ source: KnowledgeSource;
2805
+ }[];
2806
+ }
2807
+
2808
+ /** What a task and its side tasks were given, newest first. */
2809
+ export interface ContextGiven {
2810
+ at: string;
2811
+ to: string;
2812
+ via: "task_context" | "playbook_start";
2813
+ playbook: { id: string; title: string; version: number } | null;
2814
+ knowledge: { id: string; title: string; status: KnowledgeStatus; confirmedBy: string | null; url: string }[];
2815
+ }
2816
+
2817
+ export type PlaybookStatus = "draft" | "awaiting_approval" | "not_approved" | "in_force" | "superseded" | "retired";
2818
+ /** What applies before a step's action: nothing, `check_gate`, `request_approval` or `request_review`. */
2819
+ export type PlaybookStepRule = "none" | "gate" | "approval" | "review";
2820
+
2821
+ export interface PlaybookStep {
2822
+ key: string;
2823
+ title: string;
2824
+ instruction: string;
2825
+ rule: PlaybookStepRule;
2826
+ /** For a gate step: the action to check, such as `payments.send`. */
2827
+ action?: string | null;
2828
+ knowledgeIds: string[];
2829
+ }
2830
+
2831
+ export interface PlaybookInput {
2832
+ name: string;
2833
+ description: string;
2834
+ required: boolean;
2835
+ }
2836
+
2837
+ export interface PlaybookData {
2838
+ id: string;
2839
+ url: string;
2840
+ /** Every version of one playbook shares it. */
2841
+ familyId: string;
2842
+ version: number;
2843
+ status: PlaybookStatus;
2844
+ title: string;
2845
+ purpose: string;
2846
+ workspaceId: string | null;
2847
+ inputs: PlaybookInput[];
2848
+ steps: PlaybookStep[];
2849
+ knowledgeIds: string[];
2850
+ note: string | null;
2851
+ approval: { id: string; url: string; status: string } | null;
2852
+ publishedAt: string | null;
2853
+ publishedBy: string | null;
2854
+ retiredAt: string | null;
2855
+ createdBy: string;
2856
+ createdAt: string;
2857
+ updatedAt: string;
2858
+ /** `procedure`: steps an agent runs. `prompt`: approved words people and agents use. */
2859
+ kind: PlaybookKind;
2860
+ /** An approved prompt's own fields; null on a procedure. */
2861
+ prompt: PromptFields | null;
2862
+ }
2863
+
2864
+ export type PlaybookKind = "procedure" | "prompt";
2865
+
2866
+ export interface PromptFields {
2867
+ /** The approved words, with `{input}` placeholders. */
2868
+ text: string;
2869
+ /** What it is not for, and how to check what it produces. */
2870
+ limitations: string | null;
2871
+ department: string | null;
2872
+ taskType: string | null;
2873
+ language: string | null;
2874
+ owner: string | null;
2875
+ ownerUserId: string | null;
2876
+ /** YYYY-MM-DD. */
2877
+ reviewDueOn: string | null;
2878
+ /** In force, and its review date has passed. */
2879
+ reviewOverdue: boolean;
2880
+ reviewedAt: string | null;
2881
+ reviewedBy: string | null;
2882
+ }
2883
+
2884
+ /** A playbook's newest version, and which one is in force. */
2885
+ export interface PlaybookSummary extends PlaybookData {
2886
+ inForce: { id: string; version: number; url: string } | null;
2887
+ }
2888
+
2889
+ export interface PlaybookDetail extends PlaybookData {
2890
+ versions: { id: string; version: number; status: PlaybookStatus; url: string }[];
2891
+ inForceId: string | null;
2892
+ knowledge: KnowledgeEntryData[];
2893
+ }
2894
+
2895
+ export interface DraftPlaybookInput {
2896
+ /** The job, as people name it. */
2897
+ title: string;
2898
+ /** The outcome. Becomes the objective of every run; for a prompt, the one line people see. */
2899
+ purpose: string;
2900
+ /** Required for a playbook; left out for a prompt, which has one step of its own. */
2901
+ steps?: {
2902
+ key?: string;
2903
+ title: string;
2904
+ instruction: string;
2905
+ rule?: PlaybookStepRule;
2906
+ action?: string;
2907
+ knowledgeIds?: string[];
2908
+ }[];
2909
+ inputs?: { name: string; description?: string; required?: boolean }[];
2910
+ knowledgeIds?: string[];
2911
+ workspaceId?: string;
2912
+ note?: string;
2913
+ /** Send instead of `steps` to draft an approved prompt. */
2914
+ prompt?: {
2915
+ /** The words, with each input as `{input name}`. */
2916
+ text: string;
2917
+ limitations?: string;
2918
+ department?: string;
2919
+ /** Such as Analyze, Create or Edit. */
2920
+ taskType?: string;
2921
+ /** Such as en-GB. */
2922
+ language?: string;
2923
+ /** The member who owns it; whoever drafts it when omitted. */
2924
+ ownerEmail?: string;
2925
+ /** YYYY-MM-DD; six months on when omitted. */
2926
+ reviewDueOn?: string;
2927
+ /** Run as a playbook, a person reviews the output before it is used. */
2928
+ checkOutput?: boolean;
2929
+ };
2930
+ }
2931
+
2932
+ export interface UsePromptInput {
2933
+ /** The prompt's inputs, by name. A placeholder not given stays in the words. */
2934
+ inputs?: Record<string, string>;
2935
+ }
2936
+
2937
+ export interface UsedPrompt {
2938
+ prompt: { id: string; title: string; version: number; url: string };
2939
+ /** The approved words with the inputs put in. */
2940
+ text: string;
2941
+ /** Required inputs not given; their placeholders are still in `text`. */
2942
+ missingInputs: string[];
2943
+ limitations: string | null;
2944
+ /** True when you named an older version and the one in force was handed out instead. */
2945
+ ranOlderVersion: boolean;
2946
+ }
2947
+
2948
+ export interface StartPlaybookInput {
2949
+ /** A name for this run; the playbook's title when omitted. */
2950
+ title?: string;
2951
+ inputs?: Record<string, string>;
2952
+ workspaceId?: string;
2953
+ flowId?: string;
2954
+ /** An open run you started under it comes back instead of a second. */
2955
+ externalId?: string;
2956
+ sessionUrl?: string;
2957
+ }
2958
+
2959
+ export interface StartedPlaybook {
2960
+ objective: TaskData;
2961
+ resumed: boolean;
2962
+ playbook: { id: string; title: string; version: number };
2963
+ /** One side task per step, in order. Empty when resumed. */
2964
+ steps: { key: string; taskId: string; title: string; rule: PlaybookStepRule }[];
2965
+ /** True when you named an older version and the one in force ran instead. */
2966
+ ranOlderVersion: boolean;
2967
+ }
2968
+
2969
+ export interface RequestPlaybookApprovalInput {
2970
+ /** Emails, names or groups; the organisation's administrators when omitted. */
2971
+ approvers?: string[];
2972
+ note?: string;
2615
2973
  }