@deliverd/sdk 0.25.1 → 0.27.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 (58) hide show
  1. package/README.md +104 -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 +395 -0
  16. package/dist/decision-token.d.ts +102 -0
  17. package/dist/decision-token.d.ts.map +1 -0
  18. package/dist/decision-token.js +139 -0
  19. package/dist/dev.d.ts.map +1 -1
  20. package/dist/dev.js +57 -2
  21. package/dist/gates.d.ts +2 -0
  22. package/dist/gates.d.ts.map +1 -1
  23. package/dist/gates.js +3 -0
  24. package/dist/governance.d.ts +94 -0
  25. package/dist/governance.d.ts.map +1 -0
  26. package/dist/governance.js +166 -0
  27. package/dist/index.d.ts +31 -0
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +35 -0
  30. package/dist/messages.d.ts.map +1 -1
  31. package/dist/messages.js +4 -0
  32. package/dist/released.d.ts +1 -1
  33. package/dist/released.d.ts.map +1 -1
  34. package/dist/released.js +3803 -0
  35. package/dist/screen.d.ts +85 -0
  36. package/dist/screen.d.ts.map +1 -0
  37. package/dist/screen.js +69 -0
  38. package/dist/tasks.d.ts +38 -1
  39. package/dist/tasks.d.ts.map +1 -1
  40. package/dist/tasks.js +67 -0
  41. package/dist/types.d.ts +656 -4
  42. package/dist/types.d.ts.map +1 -1
  43. package/package.json +2 -2
  44. package/src/adapters/index.ts +11 -0
  45. package/src/adapters/mastra.ts +118 -0
  46. package/src/adapters/muse-spark.ts +147 -0
  47. package/src/adapters/shared.ts +2 -1
  48. package/src/data-screen.ts +536 -0
  49. package/src/decision-token.ts +184 -0
  50. package/src/dev.ts +63 -2
  51. package/src/gates.ts +3 -0
  52. package/src/governance.ts +204 -0
  53. package/src/index.ts +60 -0
  54. package/src/messages.ts +4 -0
  55. package/src/released.ts +3804 -0
  56. package/src/screen.ts +144 -0
  57. package/src/tasks.ts +88 -0
  58. package/src/types.ts +646 -4
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;
@@ -779,10 +823,11 @@ export interface WebhookEvent {
779
823
 
780
824
  /**
781
825
  * How an endpoint's body is shaped: the signed JSON envelope, a Slack Block
782
- * Kit message for an Incoming Webhook, or a Teams Adaptive Card for a
783
- * Workflows webhook. The signature headers are sent with all three.
826
+ * Kit message for an Incoming Webhook, a Teams Adaptive Card for a Workflows
827
+ * webhook, or a Discord embed with a link button for a channel webhook. The
828
+ * signature headers are sent with all four.
784
829
  */
785
- export type WebhookEndpointFormat = "json" | "slack" | "teams";
830
+ export type WebhookEndpointFormat = "json" | "slack" | "teams" | "discord";
786
831
 
787
832
  /** An organisation's webhook endpoint, as `deliverd.webhookEndpoints` reads it. Never its secret. */
788
833
  export interface WebhookEndpoint {
@@ -905,6 +950,14 @@ export interface CreateReviewInput {
905
950
  * siblings set this for you.
906
951
  */
907
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;
908
961
  /**
909
962
  * Where to POST the outcome when a person answers, instead of polling:
910
963
  * HTTPS, and a public address. The call that makes the request returns the
@@ -947,6 +1000,10 @@ export interface ReviewData {
947
1000
  threadCount: number;
948
1001
  settledAt: string | null;
949
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;
950
1007
  createdAt: string;
951
1008
  }
952
1009
 
@@ -1028,6 +1085,14 @@ export interface CreateCollectionInput {
1028
1085
  * siblings set this for you.
1029
1086
  */
1030
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;
1031
1096
  /**
1032
1097
  * Where to POST the outcome when a person answers, instead of polling:
1033
1098
  * HTTPS, and a public address. The call that makes the request returns the
@@ -1074,6 +1139,10 @@ export interface CollectionData {
1074
1139
  settledAt: string | null;
1075
1140
  dueAt: string | null;
1076
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;
1077
1146
  createdAt: string;
1078
1147
  }
1079
1148
 
@@ -1776,6 +1845,530 @@ export interface GovernanceGate {
1776
1845
  blockers: GovernanceBlocker[];
1777
1846
  }
1778
1847
 
1848
+ /*
1849
+ * The rest of Compliance Mode: the register of AI systems, what an agent may
1850
+ * do on its own, AI incidents and their DORA reports, the frameworks and how
1851
+ * they map onto controls, the ICT third-party register, the organisation's
1852
+ * governance in counts, and a governed task's evidence pack. Business and
1853
+ * Enterprise; a plan without it is refused with `feature_unavailable`.
1854
+ */
1855
+
1856
+ export type GovernanceRisk = "low" | "medium" | "high" | "critical";
1857
+ export type GovernanceOversight = NonNullable<GovernanceProfileInput["oversight"]>;
1858
+ export type DataClassification = NonNullable<GovernanceProfileInput["dataClassification"]>;
1859
+
1860
+ /** Something governed work does, for the authority check. */
1861
+ export type AuthorityAction =
1862
+ | "read"
1863
+ | "analyse"
1864
+ | "recommend"
1865
+ | "draft"
1866
+ | "modify"
1867
+ | "execute"
1868
+ | "publish"
1869
+ | "deploy"
1870
+ | "send"
1871
+ | "delete"
1872
+ | "financial_action"
1873
+ | "customer_decision";
1874
+
1875
+ /** One entry in the organisation's register of AI systems. */
1876
+ export interface AiSystem {
1877
+ id: string;
1878
+ orgId: string;
1879
+ name: string;
1880
+ provider: string | null;
1881
+ model: string | null;
1882
+ modelVersion: string | null;
1883
+ /** A digest of the prompt it runs with, never the prompt. */
1884
+ promptHash: string | null;
1885
+ /** A digest of its guardrail configuration. */
1886
+ guardrailsHash: string | null;
1887
+ purpose: string | null;
1888
+ businessOwner: string | null;
1889
+ technicalOwner: string | null;
1890
+ environment: "development" | "pilot" | "production";
1891
+ risk: GovernanceRisk;
1892
+ oversight: GovernanceOversight | null;
1893
+ dataClassification: DataClassification | null;
1894
+ personalData: boolean;
1895
+ customerFacing: boolean;
1896
+ status: "active" | "retired";
1897
+ /** The contract in the ICT third-party register it runs under. */
1898
+ ictArrangementId: string | null;
1899
+ createdByLabel: string;
1900
+ createdAt: string;
1901
+ updatedAt: string;
1902
+ }
1903
+
1904
+ export interface RegisterAiSystemInput {
1905
+ name: string;
1906
+ /** OpenAI, Anthropic, an internal team… */
1907
+ provider?: string | null;
1908
+ model?: string | null;
1909
+ modelVersion?: string | null;
1910
+ /** A digest of the prompt (`sha256:…`, a commit, a version tag), never the prompt. */
1911
+ promptHash?: string | null;
1912
+ /** A digest of the guardrail configuration, never the configuration. */
1913
+ guardrailsHash?: string | null;
1914
+ purpose?: string | null;
1915
+ businessOwner?: string | null;
1916
+ technicalOwner?: string | null;
1917
+ environment?: AiSystem["environment"];
1918
+ risk?: GovernanceRisk;
1919
+ oversight?: GovernanceOversight | null;
1920
+ dataClassification?: DataClassification | null;
1921
+ personalData?: boolean;
1922
+ customerFacing?: boolean;
1923
+ /** The contract in the ICT third-party register it runs under. */
1924
+ ictArrangementId?: string | null;
1925
+ }
1926
+
1927
+ /** An agent may raise a system's risk but not lower it, and may not retire it. */
1928
+ export interface UpdateAiSystemInput extends Partial<RegisterAiSystemInput> {
1929
+ status?: AiSystem["status"];
1930
+ }
1931
+
1932
+ /** One AI system, and the governed tasks that name it. */
1933
+ export interface AiSystemDetail {
1934
+ system: AiSystem;
1935
+ governedTaskIds: string[];
1936
+ }
1937
+
1938
+ /** A new provider, model, version, prompt or guardrails for a system. Name at least one. */
1939
+ export interface ModelChangeInput {
1940
+ provider?: string | null;
1941
+ model?: string | null;
1942
+ modelVersion?: string | null;
1943
+ promptHash?: string | null;
1944
+ guardrailsHash?: string | null;
1945
+ /** What changed and why, for the record. */
1946
+ note?: string;
1947
+ }
1948
+
1949
+ export interface ModelChangeResult {
1950
+ system: AiSystem;
1951
+ /** The reassessment opened on each governed task that uses it. */
1952
+ reassessments: Reassessment[];
1953
+ /** Which of provider, model, modelVersion, promptHash and guardrailsHash changed. */
1954
+ changed: string[];
1955
+ }
1956
+
1957
+ /** A governed task's reassessment. Its governance gate stays closed until a person completes it. */
1958
+ export interface Reassessment {
1959
+ id: string;
1960
+ taskId: string;
1961
+ trigger: "profile_change" | "model_change" | "framework_version" | "policy_version" | "incident" | "manual";
1962
+ changes: { field: string; before: unknown; after: unknown; label: string }[];
1963
+ /** Controls to look at again. */
1964
+ recheck: string[];
1965
+ reason: string;
1966
+ status: "open" | "completed";
1967
+ openedByLabel: string;
1968
+ openedByAgentId: string | null;
1969
+ openedAt: string;
1970
+ completedByLabel: string | null;
1971
+ completedAt: string | null;
1972
+ completionNote: string | null;
1973
+ }
1974
+
1975
+ export interface ReassessmentResult {
1976
+ reassessment: Reassessment;
1977
+ governance: Governance;
1978
+ }
1979
+
1980
+ /** What an agent may do: on its own, only with a person's approval, or not at all. */
1981
+ export interface AuthorityDecision {
1982
+ action: AuthorityAction;
1983
+ mode: "allowed" | "approval" | "denied";
1984
+ /** Which setting decided it: the organisation's, the agent's own, or the default. */
1985
+ source: "organisation" | "agent" | "default";
1986
+ reason: string;
1987
+ agentId: string | null;
1988
+ agentName: string | null;
1989
+ }
1990
+
1991
+ export interface CheckAuthorityInput {
1992
+ action: AuthorityAction;
1993
+ /** An agent of this organisation; the agent whose key this is when omitted. */
1994
+ agentId?: string;
1995
+ }
1996
+
1997
+ export interface ReportIncidentInput {
1998
+ /** The governed task it concerns. Give this, `aiSystemId`, or both. */
1999
+ taskId?: string;
2000
+ /** The AI system it concerns; the task's own when only `taskId` is given. */
2001
+ aiSystemId?: string;
2002
+ title: string;
2003
+ description?: string;
2004
+ /** `high` or `critical` closes the task's governance gate until a person resolves it. */
2005
+ severity: GovernanceRisk;
2006
+ /** When the organisation became aware of it, if earlier than now. DORA's clocks start here. */
2007
+ detectedAt?: string;
2008
+ }
2009
+
2010
+ /** A DORA classification a person recorded. */
2011
+ export interface DoraClassification {
2012
+ facts: Record<string, unknown>;
2013
+ major: boolean;
2014
+ criteria: { criterion: string; met: boolean; detail: string }[];
2015
+ /** The verdict in a sentence. */
2016
+ reason: string;
2017
+ /** Which version of the rules worked it out. */
2018
+ rules: string;
2019
+ }
2020
+
2021
+ export interface AiIncident {
2022
+ id: string;
2023
+ taskId: string | null;
2024
+ aiSystemId: string | null;
2025
+ title: string;
2026
+ description: string;
2027
+ severity: GovernanceRisk;
2028
+ status: "open" | "resolved";
2029
+ reportedByLabel: string;
2030
+ reportedByAgentId: string | null;
2031
+ reportedAt: string;
2032
+ resolution: string | null;
2033
+ resolvedByLabel: string | null;
2034
+ resolvedAt: string | null;
2035
+ detectedAt: string;
2036
+ /** Null until a person classifies it. */
2037
+ dora: DoraClassification | null;
2038
+ /** When it was first classified major; the reporting clock runs from here. */
2039
+ doraMajorAt: string | null;
2040
+ doraClassifiedAt: string | null;
2041
+ doraClassifiedBy: string | null;
2042
+ }
2043
+
2044
+ export type DoraReportKind = "initial" | "intermediate" | "final" | "reclassification";
2045
+
2046
+ export interface IncidentReport {
2047
+ id: string;
2048
+ incidentId: string;
2049
+ kind: DoraReportKind;
2050
+ content: string;
2051
+ fields: Record<string, unknown>;
2052
+ approvalId: string | null;
2053
+ /** The sign-off approval's state; null when none was asked for. */
2054
+ approvalStatus: string | null;
2055
+ submittedAt: string | null;
2056
+ submittedByLabel: string | null;
2057
+ authorityReference: string | null;
2058
+ createdByLabel: string;
2059
+ createdByAgentId: string | null;
2060
+ createdAt: string;
2061
+ }
2062
+
2063
+ export interface ReportingStep {
2064
+ kind: DoraReportKind;
2065
+ /** Null until the step before it is done. */
2066
+ dueAt: string | null;
2067
+ submittedAt: string | null;
2068
+ overdue: boolean;
2069
+ late: boolean;
2070
+ }
2071
+
2072
+ /** Which DORA report is due next and by when. Nothing is due unless the incident is classified major. */
2073
+ export interface ReportingSchedule {
2074
+ required: boolean;
2075
+ steps: ReportingStep[];
2076
+ next: ReportingStep | null;
2077
+ }
2078
+
2079
+ /** One incident with its reports and reporting schedule. */
2080
+ export interface AiIncidentDetail {
2081
+ id: string;
2082
+ taskId: string | null;
2083
+ aiSystemId: string | null;
2084
+ title: string;
2085
+ description: string;
2086
+ severity: GovernanceRisk;
2087
+ status: "open" | "resolved";
2088
+ reportedByLabel: string;
2089
+ reportedByAgentId: string | null;
2090
+ reportedAt: string;
2091
+ resolution: string | null;
2092
+ resolvedByLabel: string | null;
2093
+ resolvedAt: string | null;
2094
+ detectedAt: string;
2095
+ /** Null until a person classifies it. */
2096
+ dora: DoraClassification | null;
2097
+ /** When it was first classified major; the reporting clock runs from here. */
2098
+ doraMajorAt: string | null;
2099
+ doraClassifiedAt: string | null;
2100
+ doraClassifiedBy: string | null;
2101
+ url: string;
2102
+ reports: IncidentReport[];
2103
+ schedule: ReportingSchedule;
2104
+ /** Notified as major, now classified as not, and the authority not yet told. */
2105
+ reclassificationOwed: boolean;
2106
+ }
2107
+
2108
+ export interface ListIncidentsInput {
2109
+ status?: "open" | "resolved";
2110
+ aiSystemId?: string;
2111
+ /** One page of this size. Leave it unset to get every row. */
2112
+ limit?: number;
2113
+ cursor?: string;
2114
+ }
2115
+
2116
+ export interface DraftIncidentReportInput {
2117
+ kind: DoraReportKind;
2118
+ /** What the report says, for the person who signs it off and for the authority. */
2119
+ content: string;
2120
+ /**
2121
+ * The report's structured fields. initial: discoveredBy, memberStates,
2122
+ * originatedAtThirdParty, businessContinuityActivated; intermediate:
2123
+ * incidentType, occurredAt, recoveredAt, authorityReference, clientsAffected,
2124
+ * figuresAreEstimates, temporaryMeasures; final: rootCause,
2125
+ * rootCauseAddressedAt, resolvedAt, grossCostsEur, financialRecoveriesEur;
2126
+ * reclassification: reason.
2127
+ */
2128
+ fields?: Record<string, unknown>;
2129
+ /** Who signs it off; the organisation's administrators when omitted. */
2130
+ approvers?: string[];
2131
+ }
2132
+
2133
+ export interface DraftedIncidentReport {
2134
+ incident: AiIncidentDetail;
2135
+ reportId: string;
2136
+ approvalId: string;
2137
+ approvalUrl: string;
2138
+ }
2139
+
2140
+ /** Conditions on a governance profile under which a requirement applies. Every one given must hold. */
2141
+ export interface RequirementAppliesWhen {
2142
+ minRisk?: GovernanceRisk;
2143
+ personalData?: boolean;
2144
+ customerFacing?: boolean;
2145
+ productionUse?: boolean;
2146
+ decisionImpact?: NonNullable<GovernanceProfileInput["decisionImpact"]>[];
2147
+ }
2148
+
2149
+ export interface FrameworkRequirement {
2150
+ /** The framework's own reference: an article, a clause. */
2151
+ ref: string;
2152
+ title: string;
2153
+ /** Controls that evidence it: common ones, or the organisation's own `custom_` controls. */
2154
+ controls: string[];
2155
+ appliesWhen?: RequirementAppliesWhen;
2156
+ }
2157
+
2158
+ export interface FrameworkSummary {
2159
+ key: string;
2160
+ name: string;
2161
+ version: string;
2162
+ versions: string[];
2163
+ source: string;
2164
+ summary: string;
2165
+ jurisdictions: string[];
2166
+ builtIn: boolean;
2167
+ status: "published" | "draft" | "retired";
2168
+ requirements: FrameworkRequirement[];
2169
+ /** Whether and at which version the organisation applies it. */
2170
+ adoption: { frameworkKey: string; version: string; active: boolean; adoptedByLabel: string; adoptedAt: string; updatedAt: string } | null;
2171
+ }
2172
+
2173
+ export interface CustomFramework {
2174
+ id: string;
2175
+ key: string;
2176
+ version: string;
2177
+ name: string;
2178
+ summary: string;
2179
+ jurisdictions: string[];
2180
+ requirements: FrameworkRequirement[];
2181
+ status: "draft" | "published" | "retired";
2182
+ effectiveFrom: string | null;
2183
+ publishedAt: string | null;
2184
+ publishedByLabel: string | null;
2185
+ createdByLabel: string;
2186
+ createdByAgentId: string | null;
2187
+ createdAt: string;
2188
+ }
2189
+
2190
+ export interface CustomControl {
2191
+ id: string;
2192
+ key: string;
2193
+ title: string;
2194
+ description: string;
2195
+ family: string;
2196
+ satisfiedBy: "evidence" | "approval";
2197
+ status: "active" | "retired";
2198
+ createdByLabel: string;
2199
+ createdAt: string;
2200
+ }
2201
+
2202
+ /** Every framework the organisation can see: the built-in packs and its own. */
2203
+ export interface FrameworkCatalogue {
2204
+ frameworks: FrameworkSummary[];
2205
+ /** The organisation's own frameworks, every version (Enterprise). */
2206
+ custom: CustomFramework[];
2207
+ customControls: CustomControl[];
2208
+ canAdopt: boolean;
2209
+ canWriteCustom: boolean;
2210
+ statement: string;
2211
+ }
2212
+
2213
+ /** An organisation's own framework (Enterprise). A draft adds nothing until a person publishes and applies it. */
2214
+ export interface CreateCustomFrameworkInput {
2215
+ /** `custom_` followed by lower case letters, digits and underscores. */
2216
+ key: string;
2217
+ /** e.g. `1.0` or `2026.10`. A change to a published framework is a new version. */
2218
+ version: string;
2219
+ name: string;
2220
+ summary?: string;
2221
+ jurisdictions?: string[];
2222
+ /** An ISO date. */
2223
+ effectiveFrom?: string;
2224
+ requirements: FrameworkRequirement[];
2225
+ }
2226
+
2227
+ export interface RequirementCoverage {
2228
+ ref: string;
2229
+ title: string;
2230
+ applies: boolean;
2231
+ controls: { key: string; status: "outstanding" | "satisfied" | "waived" | "missing" }[];
2232
+ /** Every mapped control satisfied or waived. Not "compliant": covered by controls that are done. */
2233
+ covered: boolean;
2234
+ }
2235
+
2236
+ /** How requirements map onto controls and, for a task, how far its controls cover each. Never a compliance verdict. */
2237
+ export interface FrameworkMapping {
2238
+ taskId: string | null;
2239
+ frameworks: {
2240
+ key: string;
2241
+ name: string;
2242
+ version: string;
2243
+ source: string;
2244
+ /** Adopted by the organisation and so adding controls to the task. */
2245
+ applied: boolean;
2246
+ applies: boolean;
2247
+ covered: number;
2248
+ applicable: number;
2249
+ requirements: RequirementCoverage[];
2250
+ }[];
2251
+ statement: string;
2252
+ }
2253
+
2254
+ export interface FrameworkMappingInput {
2255
+ /** A governed task, to see how far its controls cover each requirement. */
2256
+ taskId?: string;
2257
+ /** One framework's key. */
2258
+ framework?: string;
2259
+ }
2260
+
2261
+ /** An entry in the ICT third-party register, with what it still lacks. Its other fields follow the DORA register templates. */
2262
+ export interface IctRegisterEntry {
2263
+ id: string;
2264
+ gaps: unknown[];
2265
+ [field: string]: unknown;
2266
+ }
2267
+
2268
+ /** The ICT third-party register, kept by a person in the app. Read-only here. */
2269
+ export interface IctRegister {
2270
+ entity: Record<string, unknown> | null;
2271
+ providers: (IctRegisterEntry & { name: string })[];
2272
+ arrangements: (IctRegisterEntry & { providerId: string; providerName: string; aiSystems: { id: string; name: string; environment: AiSystem["environment"] }[] })[];
2273
+ /** How many AI systems, and which critical or important functions, depend on each provider. */
2274
+ concentration: Record<string, unknown>[];
2275
+ /** Active AI systems not yet linked to an arrangement. */
2276
+ unregisteredSystems: { id: string; name: string; environment: AiSystem["environment"] }[];
2277
+ /** Which version of the regulation's lists this follows. */
2278
+ rules: string;
2279
+ }
2280
+
2281
+ export interface GovernanceSummaryInput {
2282
+ aiSystemId?: string;
2283
+ risk?: GovernanceRisk;
2284
+ owner?: string;
2285
+ provider?: string;
2286
+ dataClassification?: string;
2287
+ /** Enterprise. */
2288
+ jurisdiction?: string;
2289
+ /** Enterprise: tasks held to this framework. */
2290
+ framework?: string;
2291
+ }
2292
+
2293
+ /** The organisation's AI governance in counts. Never a compliance percentage. */
2294
+ export interface GovernanceSummary {
2295
+ aiSystems: number;
2296
+ production: number;
2297
+ elevatedOrHighRisk: number;
2298
+ governedTasks: number;
2299
+ outstandingControls: number;
2300
+ approvalsPending: number;
2301
+ expiredExceptions: number;
2302
+ openIncidents: number;
2303
+ tasksRequiringReview: number;
2304
+ systemsRequiringReview: number;
2305
+ tasks: {
2306
+ taskId: string;
2307
+ title: string;
2308
+ risk: GovernanceRisk;
2309
+ aiSystem: string | null;
2310
+ controls: { required: number; outstanding: number };
2311
+ reassessmentOpen: boolean;
2312
+ reviewOverdue: boolean;
2313
+ }[];
2314
+ filters: GovernanceSummaryInput;
2315
+ advancedFilters: boolean;
2316
+ }
2317
+
2318
+ /**
2319
+ * A governed task's evidence pack: profile, controls, evidence, task graph,
2320
+ * decisions, approvals and the audit timeline, with a digest. It assists
2321
+ * audit; it does not certify compliance. Every export is audited.
2322
+ */
2323
+ export interface GovernancePack {
2324
+ packKind: "ai_governance";
2325
+ packVersion: number;
2326
+ generatedAt: string;
2327
+ generatedBy: string;
2328
+ organisation: { id: string; name: string };
2329
+ statement: string;
2330
+ subject: { taskId: string; title: string; objective: string; url: string };
2331
+ aiSystem: AiSystem | null;
2332
+ profile: GovernanceProfileInput & { requiredByPolicy: boolean };
2333
+ readiness: GovernanceReadiness;
2334
+ gate: GovernanceGate;
2335
+ controls: GovernanceControl[];
2336
+ evidence: GovernanceEvidence[];
2337
+ frameworks: (GovernanceFramework & { requirements: RequirementCoverage[] })[];
2338
+ frameworkStatement: string | null;
2339
+ policies: Record<string, unknown>[];
2340
+ exceptions: Record<string, unknown>[];
2341
+ review: Record<string, unknown>;
2342
+ reassessments: Reassessment[];
2343
+ incidents: AiIncident[];
2344
+ thirdParty: Record<string, unknown> | null;
2345
+ doraReporting: Record<string, unknown>[];
2346
+ taskGraph: { id: string; parentTaskId: string | null; kind: string; title: string; status: string; outcome: string | null; result: string | null }[];
2347
+ findings: { taskId: string; kind: string; title: string; body: string; decisionStatus: string | null; decidedBy: string | null; recordedBy: string; at: string }[];
2348
+ approvals: { id: string; status: string; for: string }[];
2349
+ timeline: { at: string; event: string; actor: string; actorType: string; metadata: Record<string, unknown> }[];
2350
+ integrity: { algorithm: "sha256"; digest: string; covers: string; doesNotCover: string };
2351
+ }
2352
+
2353
+ export interface UpdateGovernanceProfileInput extends GovernanceProfileInput {
2354
+ /** The version you read; refused if somebody wrote in between. */
2355
+ expectedVersion?: number;
2356
+ }
2357
+
2358
+ export interface ControlApprovalInput {
2359
+ /** Emails, names or groups; the organisation's administrators when omitted. */
2360
+ approvers?: string[];
2361
+ note?: string;
2362
+ /** An ISO time. */
2363
+ expiresAt?: string;
2364
+ }
2365
+
2366
+ export interface ControlApprovalResult {
2367
+ governance: Governance;
2368
+ approvalId: string;
2369
+ approvalUrl: string;
2370
+ }
2371
+
1779
2372
  export interface ListTasksInput {
1780
2373
  /** A status, or `active` for anything not completed or cancelled. */
1781
2374
  status?: TaskStatus | "active";
@@ -1971,3 +2564,52 @@ export interface CallbackEnvelope {
1971
2564
  requestId: string;
1972
2565
  data: Record<string, unknown>;
1973
2566
  }
2567
+
2568
+ // ── Screening ──────────────────────────────────────────────────────────────
2569
+
2570
+ /** `allow` | `redact` | `ask` | `deny`: what may happen to text bound for a model. */
2571
+ export type ScreenVerdict = "allow" | "redact" | "ask" | "deny";
2572
+
2573
+ /** The AI register's record for the model the text is going to. */
2574
+ export interface ScreenTargetData {
2575
+ aiSystemId: string;
2576
+ name: string;
2577
+ /** The highest classification it is approved to receive; null when the record does not say. */
2578
+ approvedClassification: string | null;
2579
+ personalData: boolean;
2580
+ }
2581
+
2582
+ /** Where one finding is in the text you screened. Never its value. */
2583
+ export interface ScreenFindingData {
2584
+ kind: string;
2585
+ label: string;
2586
+ start: number;
2587
+ end: number;
2588
+ }
2589
+
2590
+ export interface ScreenApprovalRef {
2591
+ id: string;
2592
+ url: string;
2593
+ status: string;
2594
+ }
2595
+
2596
+ /** What `POST /screen` answers: the verdict, and why. */
2597
+ export interface ScreenData {
2598
+ verdict: ScreenVerdict;
2599
+ /** Whether the text may be sent now: as it is for `allow`, redacted for `redact`. */
2600
+ allowed: boolean;
2601
+ classification: "public" | "internal" | "confidential" | "restricted";
2602
+ personalData: boolean;
2603
+ categories: string[];
2604
+ /** What was found, by kind. */
2605
+ counts: Record<string, number>;
2606
+ /** The kinds behind the verdict: what redaction replaces. */
2607
+ offending: string[];
2608
+ reasons: string[];
2609
+ target: ScreenTargetData | null;
2610
+ /** Only when the server read the text. The SDK screens locally, so this is null from `screen()`. */
2611
+ findings: ScreenFindingData[] | null;
2612
+ redactedText: string | null;
2613
+ /** The approval a person decides, for an `ask` verdict. */
2614
+ approval: ScreenApprovalRef | null;
2615
+ }