@deliverd/sdk 0.26.0 → 0.28.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/types.ts CHANGED
@@ -240,6 +240,12 @@ export interface GateData {
240
240
  description: string | null;
241
241
  requestedBy: string;
242
242
  createdAt: string | null;
243
+ /**
244
+ * The yes, signed, while `canExecute` is true and the deployment signs:
245
+ * pass it to the code that performs the action, which checks it with
246
+ * `deliverd.decisionTokens.verify` before it acts. Null otherwise.
247
+ */
248
+ decisionToken?: string | null;
243
249
  /** Returned once, by the call that made the gate and named a callbackUrl. */
244
250
  callbackSecret?: string;
245
251
  /** On a single read: what has been reported against it. */
@@ -264,6 +270,8 @@ export interface GateDecision {
264
270
  changes: FieldChange[];
265
271
  id: string;
266
272
  approvalUrl: string | null;
273
+ /** The signed yes, for the code that performs the action to verify. Null unless it may be acted on now. */
274
+ decisionToken: string | null;
267
275
  gate: unknown;
268
276
  }
269
277
 
@@ -294,6 +302,26 @@ export interface ApprovalQuestion {
294
302
  answeredAt: string | null;
295
303
  }
296
304
 
305
+ /**
306
+ * Which agent is asking, as you describe it on a request. Every field is
307
+ * optional; name the ones you know.
308
+ */
309
+ export interface RequestAgent {
310
+ /** What the agent is called, as people know it. */
311
+ name?: string;
312
+ /** Who makes or runs it: anthropic, openai, cursor, your own company. */
313
+ provider?: string;
314
+ /** Your own id for this agent. */
315
+ externalId?: string;
316
+ }
317
+
318
+ /** The agent a request declared, as the API returns it. */
319
+ export interface DeclaredAgent {
320
+ name: string | null;
321
+ provider: string | null;
322
+ externalId: string | null;
323
+ }
324
+
297
325
  export interface ApprovalData {
298
326
  id: string;
299
327
  status: ApprovalStatus;
@@ -340,6 +368,10 @@ export interface ApprovalData {
340
368
  note: string | null;
341
369
  expiresAt: string | null;
342
370
  questions: ApprovalQuestion[];
371
+ /** Which agent asked, as the request declared it. Null when it said nothing. Not verified. */
372
+ agent: DeclaredAgent | null;
373
+ /** The model the request said the agent was running on. Not verified. */
374
+ model: string | null;
343
375
  createdAt: string;
344
376
  }
345
377
 
@@ -379,6 +411,14 @@ export interface CreateApprovalInput {
379
411
  * siblings set this for you.
380
412
  */
381
413
  flowId?: string;
414
+ /**
415
+ * Which agent is asking, in your words. One key is often shared by
416
+ * several agents; this says which one was holding it. Recorded, returned
417
+ * and shown as declared — nothing is decided on it.
418
+ */
419
+ agent?: RequestAgent;
420
+ /** The model the agent is running on, such as `claude-opus-5`. Recorded as declared. */
421
+ model?: string;
382
422
  /**
383
423
  * Where to POST the outcome when a person answers, instead of polling:
384
424
  * HTTPS, and a public address. The call that makes the request returns the
@@ -767,7 +807,11 @@ export type WebhookEventName =
767
807
  /** Opt-in: a task moved into blocked, or a side task finished and its
768
808
  * result waits to be applied, kept or discarded. */
769
809
  | "task.blocked"
770
- | "side_task.completed";
810
+ | "side_task.completed"
811
+ /** An AI risk indicator went red for a month: its figure, limits and owner. */
812
+ | "risk_indicator.breached"
813
+ /** Opt-in: one audit log entry, with its chain position and hashes. For a SIEM. */
814
+ | "audit.event";
771
815
 
772
816
  export interface WebhookEvent {
773
817
  event: WebhookEventName;
@@ -906,6 +950,14 @@ export interface CreateReviewInput {
906
950
  * siblings set this for you.
907
951
  */
908
952
  flowId?: string;
953
+ /**
954
+ * Which agent is asking, in your words. One key is often shared by
955
+ * several agents; this says which one was holding it. Recorded, returned
956
+ * and shown as declared — nothing is decided on it.
957
+ */
958
+ agent?: RequestAgent;
959
+ /** The model the agent is running on, such as `claude-opus-5`. Recorded as declared. */
960
+ model?: string;
909
961
  /**
910
962
  * Where to POST the outcome when a person answers, instead of polling:
911
963
  * HTTPS, and a public address. The call that makes the request returns the
@@ -948,6 +1000,10 @@ export interface ReviewData {
948
1000
  threadCount: number;
949
1001
  settledAt: string | null;
950
1002
  expiresAt: string | null;
1003
+ /** Which agent asked, as the request declared it. Null when it said nothing. Not verified. */
1004
+ agent: DeclaredAgent | null;
1005
+ /** The model the request said the agent was running on. Not verified. */
1006
+ model: string | null;
951
1007
  createdAt: string;
952
1008
  }
953
1009
 
@@ -1029,6 +1085,14 @@ export interface CreateCollectionInput {
1029
1085
  * siblings set this for you.
1030
1086
  */
1031
1087
  flowId?: string;
1088
+ /**
1089
+ * Which agent is asking, in your words. One key is often shared by
1090
+ * several agents; this says which one was holding it. Recorded, returned
1091
+ * and shown as declared — nothing is decided on it.
1092
+ */
1093
+ agent?: RequestAgent;
1094
+ /** The model the agent is running on, such as `claude-opus-5`. Recorded as declared. */
1095
+ model?: string;
1032
1096
  /**
1033
1097
  * Where to POST the outcome when a person answers, instead of polling:
1034
1098
  * HTTPS, and a public address. The call that makes the request returns the
@@ -1075,6 +1139,10 @@ export interface CollectionData {
1075
1139
  settledAt: string | null;
1076
1140
  dueAt: string | null;
1077
1141
  expiresAt: string | null;
1142
+ /** Which agent asked, as the request declared it. Null when it said nothing. Not verified. */
1143
+ agent: DeclaredAgent | null;
1144
+ /** The model the request said the agent was running on. Not verified. */
1145
+ model: string | null;
1078
1146
  createdAt: string;
1079
1147
  }
1080
1148
 
@@ -1432,10 +1500,38 @@ export interface TaskContext {
1432
1500
  * `reports.update()` rather than publishing a second on the same thing.
1433
1501
  */
1434
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;
1435
1511
  /** One paragraph to say back to yourself to re-anchor on the objective. */
1436
1512
  reanchor: string;
1437
1513
  }
1438
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
+
1439
1535
  /** A report published for a task, as its context names it. */
1440
1536
  export interface TaskContextReport {
1441
1537
  id: string;
@@ -2545,3 +2641,263 @@ export interface ScreenData {
2545
2641
  /** The approval a person decides, for an `ask` verdict. */
2546
2642
  approval: ScreenApprovalRef | null;
2547
2643
  }
2644
+
2645
+ // ── Context: knowledge and playbooks ────────────────────────────────────────
2646
+
2647
+ export type KnowledgeKind = "fact" | "convention" | "decision" | "procedure" | "glossary" | "contact" | "known_issue";
2648
+ export type KnowledgeStatus = "proposed" | "confirmed" | "rejected" | "retired" | "superseded";
2649
+ /** `open` is proposed and confirmed together. */
2650
+ export type KnowledgeStatusFilter = KnowledgeStatus | "open" | "all";
2651
+
2652
+ /** Where an entry came from. */
2653
+ export interface KnowledgeSource {
2654
+ kind: "manual" | "finding" | "decision" | "import" | "url" | "agent";
2655
+ id?: string;
2656
+ url?: string;
2657
+ label?: string;
2658
+ }
2659
+
2660
+ /** One entry of the organisation's knowledge. Only `confirmed` is to be relied on. */
2661
+ export interface KnowledgeEntryData {
2662
+ id: string;
2663
+ url: string;
2664
+ kind: KnowledgeKind;
2665
+ kindLabel: string;
2666
+ title: string;
2667
+ body: string;
2668
+ tags: string[];
2669
+ status: KnowledgeStatus;
2670
+ workspaceId: string | null;
2671
+ flowId: string | null;
2672
+ /** The confirmed entry this replaces once it is confirmed. */
2673
+ supersedesId: string | null;
2674
+ supersededById: string | null;
2675
+ source: KnowledgeSource;
2676
+ owner: string | null;
2677
+ reviewDueOn: string | null;
2678
+ reviewOverdue: boolean;
2679
+ lastReviewedAt: string | null;
2680
+ confirmedBy: string | null;
2681
+ confirmedAt: string | null;
2682
+ decisionNote: string | null;
2683
+ retiredAt: string | null;
2684
+ retiredReason: string | null;
2685
+ externalId: string | null;
2686
+ proposedBy: string;
2687
+ createdAt: string;
2688
+ updatedAt: string;
2689
+ }
2690
+
2691
+ export interface KnowledgeDetail extends KnowledgeEntryData {
2692
+ /** Earlier versions this replaced and later ones that replaced it, oldest first. */
2693
+ history: { id: string; title: string; status: KnowledgeStatus; confirmedAt: string | null; url: string }[];
2694
+ /** A proposed revision waiting for a person, on a confirmed entry. */
2695
+ pendingRevision: { id: string; title: string; url: string } | null;
2696
+ }
2697
+
2698
+ export interface ProposeKnowledgeInput {
2699
+ kind: KnowledgeKind;
2700
+ /** The fact or rule in one line. */
2701
+ title: string;
2702
+ /** The detail another agent needs to act on it. A secret is refused. */
2703
+ body: string;
2704
+ tags?: string[];
2705
+ /** One workspace only; the whole organisation when omitted. */
2706
+ workspaceId?: string;
2707
+ flowId?: string;
2708
+ /** The confirmed entry this would replace, once a person confirms it. */
2709
+ supersedesId?: string;
2710
+ sourceUrl?: string;
2711
+ sourceLabel?: string;
2712
+ /** Your own reference. An open entry with the same one comes back instead of a second. */
2713
+ externalId?: string;
2714
+ }
2715
+
2716
+ export interface ProposedKnowledge {
2717
+ entry: KnowledgeEntryData;
2718
+ resumed: boolean;
2719
+ /** Personal data seen in what you wrote, said back to you; null when none. */
2720
+ screening: string | null;
2721
+ }
2722
+
2723
+ export interface EditKnowledgeInput {
2724
+ kind?: KnowledgeKind;
2725
+ title?: string;
2726
+ body?: string;
2727
+ tags?: string[];
2728
+ }
2729
+
2730
+ export interface SearchKnowledgeInput {
2731
+ /** Words, ranked by relevance. Omit for the newest. */
2732
+ q?: string;
2733
+ kind?: KnowledgeKind;
2734
+ /** `confirmed` when omitted. */
2735
+ status?: KnowledgeStatusFilter;
2736
+ workspaceId?: string;
2737
+ flowId?: string;
2738
+ limit?: number;
2739
+ }
2740
+
2741
+ export interface KnowledgeSearchResult {
2742
+ entries: KnowledgeEntryData[];
2743
+ /** True when the list was cut at the limit. */
2744
+ more: boolean;
2745
+ }
2746
+
2747
+ export interface PromoteFindingInput {
2748
+ kind?: KnowledgeKind;
2749
+ title?: string;
2750
+ body?: string;
2751
+ tags?: string[];
2752
+ }
2753
+
2754
+ export interface ImportKnowledgeInput {
2755
+ /** A Deliverd export, or a notes file such as AGENTS.md. Each heading becomes one proposed entry. */
2756
+ markdown: string;
2757
+ workspaceId?: string;
2758
+ /** Where the file came from, e.g. the repository and path. */
2759
+ source?: string;
2760
+ }
2761
+
2762
+ export interface ImportedKnowledge {
2763
+ created: KnowledgeEntryData[];
2764
+ skipped: { title: string; reason: string }[];
2765
+ }
2766
+
2767
+ export interface ExportKnowledgeInput {
2768
+ /** `confirmed` when omitted. */
2769
+ status?: KnowledgeStatusFilter;
2770
+ workspaceId?: string;
2771
+ }
2772
+
2773
+ /** A JSON export: portable entries, with their scope named rather than numbered. */
2774
+ export interface KnowledgeExport {
2775
+ format: "deliverd-knowledge";
2776
+ version: 1;
2777
+ organisation: string;
2778
+ exportedAt: string;
2779
+ entries: {
2780
+ id?: string;
2781
+ kind: KnowledgeKind;
2782
+ title: string;
2783
+ body: string;
2784
+ tags: string[];
2785
+ status?: KnowledgeStatus;
2786
+ /** The workspace's name, or Organisation. */
2787
+ scope?: string | null;
2788
+ owner?: string | null;
2789
+ confirmedBy?: string | null;
2790
+ confirmedOn?: string | null;
2791
+ reviewDueOn?: string | null;
2792
+ source: KnowledgeSource;
2793
+ }[];
2794
+ }
2795
+
2796
+ /** What a task and its side tasks were given, newest first. */
2797
+ export interface ContextGiven {
2798
+ at: string;
2799
+ to: string;
2800
+ via: "task_context" | "playbook_start";
2801
+ playbook: { id: string; title: string; version: number } | null;
2802
+ knowledge: { id: string; title: string; status: KnowledgeStatus; confirmedBy: string | null; url: string }[];
2803
+ }
2804
+
2805
+ export type PlaybookStatus = "draft" | "awaiting_approval" | "not_approved" | "in_force" | "superseded" | "retired";
2806
+ /** What applies before a step's action: nothing, `check_gate`, `request_approval` or `request_review`. */
2807
+ export type PlaybookStepRule = "none" | "gate" | "approval" | "review";
2808
+
2809
+ export interface PlaybookStep {
2810
+ key: string;
2811
+ title: string;
2812
+ instruction: string;
2813
+ rule: PlaybookStepRule;
2814
+ /** For a gate step: the action to check, such as `payments.send`. */
2815
+ action?: string | null;
2816
+ knowledgeIds: string[];
2817
+ }
2818
+
2819
+ export interface PlaybookInput {
2820
+ name: string;
2821
+ description: string;
2822
+ required: boolean;
2823
+ }
2824
+
2825
+ export interface PlaybookData {
2826
+ id: string;
2827
+ url: string;
2828
+ /** Every version of one playbook shares it. */
2829
+ familyId: string;
2830
+ version: number;
2831
+ status: PlaybookStatus;
2832
+ title: string;
2833
+ purpose: string;
2834
+ workspaceId: string | null;
2835
+ inputs: PlaybookInput[];
2836
+ steps: PlaybookStep[];
2837
+ knowledgeIds: string[];
2838
+ note: string | null;
2839
+ approval: { id: string; url: string; status: string } | null;
2840
+ publishedAt: string | null;
2841
+ publishedBy: string | null;
2842
+ retiredAt: string | null;
2843
+ createdBy: string;
2844
+ createdAt: string;
2845
+ updatedAt: string;
2846
+ }
2847
+
2848
+ /** A playbook's newest version, and which one is in force. */
2849
+ export interface PlaybookSummary extends PlaybookData {
2850
+ inForce: { id: string; version: number; url: string } | null;
2851
+ }
2852
+
2853
+ export interface PlaybookDetail extends PlaybookData {
2854
+ versions: { id: string; version: number; status: PlaybookStatus; url: string }[];
2855
+ inForceId: string | null;
2856
+ knowledge: KnowledgeEntryData[];
2857
+ }
2858
+
2859
+ export interface DraftPlaybookInput {
2860
+ /** The job, as people name it. */
2861
+ title: string;
2862
+ /** The outcome. Becomes the objective of every run. */
2863
+ purpose: string;
2864
+ steps: {
2865
+ key?: string;
2866
+ title: string;
2867
+ instruction: string;
2868
+ rule?: PlaybookStepRule;
2869
+ action?: string;
2870
+ knowledgeIds?: string[];
2871
+ }[];
2872
+ inputs?: { name: string; description?: string; required?: boolean }[];
2873
+ knowledgeIds?: string[];
2874
+ workspaceId?: string;
2875
+ note?: string;
2876
+ }
2877
+
2878
+ export interface StartPlaybookInput {
2879
+ /** A name for this run; the playbook's title when omitted. */
2880
+ title?: string;
2881
+ inputs?: Record<string, string>;
2882
+ workspaceId?: string;
2883
+ flowId?: string;
2884
+ /** An open run you started under it comes back instead of a second. */
2885
+ externalId?: string;
2886
+ sessionUrl?: string;
2887
+ }
2888
+
2889
+ export interface StartedPlaybook {
2890
+ objective: TaskData;
2891
+ resumed: boolean;
2892
+ playbook: { id: string; title: string; version: number };
2893
+ /** One side task per step, in order. Empty when resumed. */
2894
+ steps: { key: string; taskId: string; title: string; rule: PlaybookStepRule }[];
2895
+ /** True when you named an older version and the one in force ran instead. */
2896
+ ranOlderVersion: boolean;
2897
+ }
2898
+
2899
+ export interface RequestPlaybookApprovalInput {
2900
+ /** Emails, names or groups; the organisation's administrators when omitted. */
2901
+ approvers?: string[];
2902
+ note?: string;
2903
+ }