@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/types.ts CHANGED
@@ -779,10 +779,11 @@ export interface WebhookEvent {
779
779
 
780
780
  /**
781
781
  * 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.
782
+ * Kit message for an Incoming Webhook, a Teams Adaptive Card for a Workflows
783
+ * webhook, or a Discord embed with a link button for a channel webhook. The
784
+ * signature headers are sent with all four.
784
785
  */
785
- export type WebhookEndpointFormat = "json" | "slack" | "teams";
786
+ export type WebhookEndpointFormat = "json" | "slack" | "teams" | "discord";
786
787
 
787
788
  /** An organisation's webhook endpoint, as `deliverd.webhookEndpoints` reads it. Never its secret. */
788
789
  export interface WebhookEndpoint {
@@ -1776,6 +1777,530 @@ export interface GovernanceGate {
1776
1777
  blockers: GovernanceBlocker[];
1777
1778
  }
1778
1779
 
1780
+ /*
1781
+ * The rest of Compliance Mode: the register of AI systems, what an agent may
1782
+ * do on its own, AI incidents and their DORA reports, the frameworks and how
1783
+ * they map onto controls, the ICT third-party register, the organisation's
1784
+ * governance in counts, and a governed task's evidence pack. Business and
1785
+ * Enterprise; a plan without it is refused with `feature_unavailable`.
1786
+ */
1787
+
1788
+ export type GovernanceRisk = "low" | "medium" | "high" | "critical";
1789
+ export type GovernanceOversight = NonNullable<GovernanceProfileInput["oversight"]>;
1790
+ export type DataClassification = NonNullable<GovernanceProfileInput["dataClassification"]>;
1791
+
1792
+ /** Something governed work does, for the authority check. */
1793
+ export type AuthorityAction =
1794
+ | "read"
1795
+ | "analyse"
1796
+ | "recommend"
1797
+ | "draft"
1798
+ | "modify"
1799
+ | "execute"
1800
+ | "publish"
1801
+ | "deploy"
1802
+ | "send"
1803
+ | "delete"
1804
+ | "financial_action"
1805
+ | "customer_decision";
1806
+
1807
+ /** One entry in the organisation's register of AI systems. */
1808
+ export interface AiSystem {
1809
+ id: string;
1810
+ orgId: string;
1811
+ name: string;
1812
+ provider: string | null;
1813
+ model: string | null;
1814
+ modelVersion: string | null;
1815
+ /** A digest of the prompt it runs with, never the prompt. */
1816
+ promptHash: string | null;
1817
+ /** A digest of its guardrail configuration. */
1818
+ guardrailsHash: string | null;
1819
+ purpose: string | null;
1820
+ businessOwner: string | null;
1821
+ technicalOwner: string | null;
1822
+ environment: "development" | "pilot" | "production";
1823
+ risk: GovernanceRisk;
1824
+ oversight: GovernanceOversight | null;
1825
+ dataClassification: DataClassification | null;
1826
+ personalData: boolean;
1827
+ customerFacing: boolean;
1828
+ status: "active" | "retired";
1829
+ /** The contract in the ICT third-party register it runs under. */
1830
+ ictArrangementId: string | null;
1831
+ createdByLabel: string;
1832
+ createdAt: string;
1833
+ updatedAt: string;
1834
+ }
1835
+
1836
+ export interface RegisterAiSystemInput {
1837
+ name: string;
1838
+ /** OpenAI, Anthropic, an internal team… */
1839
+ provider?: string | null;
1840
+ model?: string | null;
1841
+ modelVersion?: string | null;
1842
+ /** A digest of the prompt (`sha256:…`, a commit, a version tag), never the prompt. */
1843
+ promptHash?: string | null;
1844
+ /** A digest of the guardrail configuration, never the configuration. */
1845
+ guardrailsHash?: string | null;
1846
+ purpose?: string | null;
1847
+ businessOwner?: string | null;
1848
+ technicalOwner?: string | null;
1849
+ environment?: AiSystem["environment"];
1850
+ risk?: GovernanceRisk;
1851
+ oversight?: GovernanceOversight | null;
1852
+ dataClassification?: DataClassification | null;
1853
+ personalData?: boolean;
1854
+ customerFacing?: boolean;
1855
+ /** The contract in the ICT third-party register it runs under. */
1856
+ ictArrangementId?: string | null;
1857
+ }
1858
+
1859
+ /** An agent may raise a system's risk but not lower it, and may not retire it. */
1860
+ export interface UpdateAiSystemInput extends Partial<RegisterAiSystemInput> {
1861
+ status?: AiSystem["status"];
1862
+ }
1863
+
1864
+ /** One AI system, and the governed tasks that name it. */
1865
+ export interface AiSystemDetail {
1866
+ system: AiSystem;
1867
+ governedTaskIds: string[];
1868
+ }
1869
+
1870
+ /** A new provider, model, version, prompt or guardrails for a system. Name at least one. */
1871
+ export interface ModelChangeInput {
1872
+ provider?: string | null;
1873
+ model?: string | null;
1874
+ modelVersion?: string | null;
1875
+ promptHash?: string | null;
1876
+ guardrailsHash?: string | null;
1877
+ /** What changed and why, for the record. */
1878
+ note?: string;
1879
+ }
1880
+
1881
+ export interface ModelChangeResult {
1882
+ system: AiSystem;
1883
+ /** The reassessment opened on each governed task that uses it. */
1884
+ reassessments: Reassessment[];
1885
+ /** Which of provider, model, modelVersion, promptHash and guardrailsHash changed. */
1886
+ changed: string[];
1887
+ }
1888
+
1889
+ /** A governed task's reassessment. Its governance gate stays closed until a person completes it. */
1890
+ export interface Reassessment {
1891
+ id: string;
1892
+ taskId: string;
1893
+ trigger: "profile_change" | "model_change" | "framework_version" | "policy_version" | "incident" | "manual";
1894
+ changes: { field: string; before: unknown; after: unknown; label: string }[];
1895
+ /** Controls to look at again. */
1896
+ recheck: string[];
1897
+ reason: string;
1898
+ status: "open" | "completed";
1899
+ openedByLabel: string;
1900
+ openedByAgentId: string | null;
1901
+ openedAt: string;
1902
+ completedByLabel: string | null;
1903
+ completedAt: string | null;
1904
+ completionNote: string | null;
1905
+ }
1906
+
1907
+ export interface ReassessmentResult {
1908
+ reassessment: Reassessment;
1909
+ governance: Governance;
1910
+ }
1911
+
1912
+ /** What an agent may do: on its own, only with a person's approval, or not at all. */
1913
+ export interface AuthorityDecision {
1914
+ action: AuthorityAction;
1915
+ mode: "allowed" | "approval" | "denied";
1916
+ /** Which setting decided it: the organisation's, the agent's own, or the default. */
1917
+ source: "organisation" | "agent" | "default";
1918
+ reason: string;
1919
+ agentId: string | null;
1920
+ agentName: string | null;
1921
+ }
1922
+
1923
+ export interface CheckAuthorityInput {
1924
+ action: AuthorityAction;
1925
+ /** An agent of this organisation; the agent whose key this is when omitted. */
1926
+ agentId?: string;
1927
+ }
1928
+
1929
+ export interface ReportIncidentInput {
1930
+ /** The governed task it concerns. Give this, `aiSystemId`, or both. */
1931
+ taskId?: string;
1932
+ /** The AI system it concerns; the task's own when only `taskId` is given. */
1933
+ aiSystemId?: string;
1934
+ title: string;
1935
+ description?: string;
1936
+ /** `high` or `critical` closes the task's governance gate until a person resolves it. */
1937
+ severity: GovernanceRisk;
1938
+ /** When the organisation became aware of it, if earlier than now. DORA's clocks start here. */
1939
+ detectedAt?: string;
1940
+ }
1941
+
1942
+ /** A DORA classification a person recorded. */
1943
+ export interface DoraClassification {
1944
+ facts: Record<string, unknown>;
1945
+ major: boolean;
1946
+ criteria: { criterion: string; met: boolean; detail: string }[];
1947
+ /** The verdict in a sentence. */
1948
+ reason: string;
1949
+ /** Which version of the rules worked it out. */
1950
+ rules: string;
1951
+ }
1952
+
1953
+ export interface AiIncident {
1954
+ id: string;
1955
+ taskId: string | null;
1956
+ aiSystemId: string | null;
1957
+ title: string;
1958
+ description: string;
1959
+ severity: GovernanceRisk;
1960
+ status: "open" | "resolved";
1961
+ reportedByLabel: string;
1962
+ reportedByAgentId: string | null;
1963
+ reportedAt: string;
1964
+ resolution: string | null;
1965
+ resolvedByLabel: string | null;
1966
+ resolvedAt: string | null;
1967
+ detectedAt: string;
1968
+ /** Null until a person classifies it. */
1969
+ dora: DoraClassification | null;
1970
+ /** When it was first classified major; the reporting clock runs from here. */
1971
+ doraMajorAt: string | null;
1972
+ doraClassifiedAt: string | null;
1973
+ doraClassifiedBy: string | null;
1974
+ }
1975
+
1976
+ export type DoraReportKind = "initial" | "intermediate" | "final" | "reclassification";
1977
+
1978
+ export interface IncidentReport {
1979
+ id: string;
1980
+ incidentId: string;
1981
+ kind: DoraReportKind;
1982
+ content: string;
1983
+ fields: Record<string, unknown>;
1984
+ approvalId: string | null;
1985
+ /** The sign-off approval's state; null when none was asked for. */
1986
+ approvalStatus: string | null;
1987
+ submittedAt: string | null;
1988
+ submittedByLabel: string | null;
1989
+ authorityReference: string | null;
1990
+ createdByLabel: string;
1991
+ createdByAgentId: string | null;
1992
+ createdAt: string;
1993
+ }
1994
+
1995
+ export interface ReportingStep {
1996
+ kind: DoraReportKind;
1997
+ /** Null until the step before it is done. */
1998
+ dueAt: string | null;
1999
+ submittedAt: string | null;
2000
+ overdue: boolean;
2001
+ late: boolean;
2002
+ }
2003
+
2004
+ /** Which DORA report is due next and by when. Nothing is due unless the incident is classified major. */
2005
+ export interface ReportingSchedule {
2006
+ required: boolean;
2007
+ steps: ReportingStep[];
2008
+ next: ReportingStep | null;
2009
+ }
2010
+
2011
+ /** One incident with its reports and reporting schedule. */
2012
+ export interface AiIncidentDetail {
2013
+ id: string;
2014
+ taskId: string | null;
2015
+ aiSystemId: string | null;
2016
+ title: string;
2017
+ description: string;
2018
+ severity: GovernanceRisk;
2019
+ status: "open" | "resolved";
2020
+ reportedByLabel: string;
2021
+ reportedByAgentId: string | null;
2022
+ reportedAt: string;
2023
+ resolution: string | null;
2024
+ resolvedByLabel: string | null;
2025
+ resolvedAt: string | null;
2026
+ detectedAt: string;
2027
+ /** Null until a person classifies it. */
2028
+ dora: DoraClassification | null;
2029
+ /** When it was first classified major; the reporting clock runs from here. */
2030
+ doraMajorAt: string | null;
2031
+ doraClassifiedAt: string | null;
2032
+ doraClassifiedBy: string | null;
2033
+ url: string;
2034
+ reports: IncidentReport[];
2035
+ schedule: ReportingSchedule;
2036
+ /** Notified as major, now classified as not, and the authority not yet told. */
2037
+ reclassificationOwed: boolean;
2038
+ }
2039
+
2040
+ export interface ListIncidentsInput {
2041
+ status?: "open" | "resolved";
2042
+ aiSystemId?: string;
2043
+ /** One page of this size. Leave it unset to get every row. */
2044
+ limit?: number;
2045
+ cursor?: string;
2046
+ }
2047
+
2048
+ export interface DraftIncidentReportInput {
2049
+ kind: DoraReportKind;
2050
+ /** What the report says, for the person who signs it off and for the authority. */
2051
+ content: string;
2052
+ /**
2053
+ * The report's structured fields. initial: discoveredBy, memberStates,
2054
+ * originatedAtThirdParty, businessContinuityActivated; intermediate:
2055
+ * incidentType, occurredAt, recoveredAt, authorityReference, clientsAffected,
2056
+ * figuresAreEstimates, temporaryMeasures; final: rootCause,
2057
+ * rootCauseAddressedAt, resolvedAt, grossCostsEur, financialRecoveriesEur;
2058
+ * reclassification: reason.
2059
+ */
2060
+ fields?: Record<string, unknown>;
2061
+ /** Who signs it off; the organisation's administrators when omitted. */
2062
+ approvers?: string[];
2063
+ }
2064
+
2065
+ export interface DraftedIncidentReport {
2066
+ incident: AiIncidentDetail;
2067
+ reportId: string;
2068
+ approvalId: string;
2069
+ approvalUrl: string;
2070
+ }
2071
+
2072
+ /** Conditions on a governance profile under which a requirement applies. Every one given must hold. */
2073
+ export interface RequirementAppliesWhen {
2074
+ minRisk?: GovernanceRisk;
2075
+ personalData?: boolean;
2076
+ customerFacing?: boolean;
2077
+ productionUse?: boolean;
2078
+ decisionImpact?: NonNullable<GovernanceProfileInput["decisionImpact"]>[];
2079
+ }
2080
+
2081
+ export interface FrameworkRequirement {
2082
+ /** The framework's own reference: an article, a clause. */
2083
+ ref: string;
2084
+ title: string;
2085
+ /** Controls that evidence it: common ones, or the organisation's own `custom_` controls. */
2086
+ controls: string[];
2087
+ appliesWhen?: RequirementAppliesWhen;
2088
+ }
2089
+
2090
+ export interface FrameworkSummary {
2091
+ key: string;
2092
+ name: string;
2093
+ version: string;
2094
+ versions: string[];
2095
+ source: string;
2096
+ summary: string;
2097
+ jurisdictions: string[];
2098
+ builtIn: boolean;
2099
+ status: "published" | "draft" | "retired";
2100
+ requirements: FrameworkRequirement[];
2101
+ /** Whether and at which version the organisation applies it. */
2102
+ adoption: { frameworkKey: string; version: string; active: boolean; adoptedByLabel: string; adoptedAt: string; updatedAt: string } | null;
2103
+ }
2104
+
2105
+ export interface CustomFramework {
2106
+ id: string;
2107
+ key: string;
2108
+ version: string;
2109
+ name: string;
2110
+ summary: string;
2111
+ jurisdictions: string[];
2112
+ requirements: FrameworkRequirement[];
2113
+ status: "draft" | "published" | "retired";
2114
+ effectiveFrom: string | null;
2115
+ publishedAt: string | null;
2116
+ publishedByLabel: string | null;
2117
+ createdByLabel: string;
2118
+ createdByAgentId: string | null;
2119
+ createdAt: string;
2120
+ }
2121
+
2122
+ export interface CustomControl {
2123
+ id: string;
2124
+ key: string;
2125
+ title: string;
2126
+ description: string;
2127
+ family: string;
2128
+ satisfiedBy: "evidence" | "approval";
2129
+ status: "active" | "retired";
2130
+ createdByLabel: string;
2131
+ createdAt: string;
2132
+ }
2133
+
2134
+ /** Every framework the organisation can see: the built-in packs and its own. */
2135
+ export interface FrameworkCatalogue {
2136
+ frameworks: FrameworkSummary[];
2137
+ /** The organisation's own frameworks, every version (Enterprise). */
2138
+ custom: CustomFramework[];
2139
+ customControls: CustomControl[];
2140
+ canAdopt: boolean;
2141
+ canWriteCustom: boolean;
2142
+ statement: string;
2143
+ }
2144
+
2145
+ /** An organisation's own framework (Enterprise). A draft adds nothing until a person publishes and applies it. */
2146
+ export interface CreateCustomFrameworkInput {
2147
+ /** `custom_` followed by lower case letters, digits and underscores. */
2148
+ key: string;
2149
+ /** e.g. `1.0` or `2026.10`. A change to a published framework is a new version. */
2150
+ version: string;
2151
+ name: string;
2152
+ summary?: string;
2153
+ jurisdictions?: string[];
2154
+ /** An ISO date. */
2155
+ effectiveFrom?: string;
2156
+ requirements: FrameworkRequirement[];
2157
+ }
2158
+
2159
+ export interface RequirementCoverage {
2160
+ ref: string;
2161
+ title: string;
2162
+ applies: boolean;
2163
+ controls: { key: string; status: "outstanding" | "satisfied" | "waived" | "missing" }[];
2164
+ /** Every mapped control satisfied or waived. Not "compliant": covered by controls that are done. */
2165
+ covered: boolean;
2166
+ }
2167
+
2168
+ /** How requirements map onto controls and, for a task, how far its controls cover each. Never a compliance verdict. */
2169
+ export interface FrameworkMapping {
2170
+ taskId: string | null;
2171
+ frameworks: {
2172
+ key: string;
2173
+ name: string;
2174
+ version: string;
2175
+ source: string;
2176
+ /** Adopted by the organisation and so adding controls to the task. */
2177
+ applied: boolean;
2178
+ applies: boolean;
2179
+ covered: number;
2180
+ applicable: number;
2181
+ requirements: RequirementCoverage[];
2182
+ }[];
2183
+ statement: string;
2184
+ }
2185
+
2186
+ export interface FrameworkMappingInput {
2187
+ /** A governed task, to see how far its controls cover each requirement. */
2188
+ taskId?: string;
2189
+ /** One framework's key. */
2190
+ framework?: string;
2191
+ }
2192
+
2193
+ /** An entry in the ICT third-party register, with what it still lacks. Its other fields follow the DORA register templates. */
2194
+ export interface IctRegisterEntry {
2195
+ id: string;
2196
+ gaps: unknown[];
2197
+ [field: string]: unknown;
2198
+ }
2199
+
2200
+ /** The ICT third-party register, kept by a person in the app. Read-only here. */
2201
+ export interface IctRegister {
2202
+ entity: Record<string, unknown> | null;
2203
+ providers: (IctRegisterEntry & { name: string })[];
2204
+ arrangements: (IctRegisterEntry & { providerId: string; providerName: string; aiSystems: { id: string; name: string; environment: AiSystem["environment"] }[] })[];
2205
+ /** How many AI systems, and which critical or important functions, depend on each provider. */
2206
+ concentration: Record<string, unknown>[];
2207
+ /** Active AI systems not yet linked to an arrangement. */
2208
+ unregisteredSystems: { id: string; name: string; environment: AiSystem["environment"] }[];
2209
+ /** Which version of the regulation's lists this follows. */
2210
+ rules: string;
2211
+ }
2212
+
2213
+ export interface GovernanceSummaryInput {
2214
+ aiSystemId?: string;
2215
+ risk?: GovernanceRisk;
2216
+ owner?: string;
2217
+ provider?: string;
2218
+ dataClassification?: string;
2219
+ /** Enterprise. */
2220
+ jurisdiction?: string;
2221
+ /** Enterprise: tasks held to this framework. */
2222
+ framework?: string;
2223
+ }
2224
+
2225
+ /** The organisation's AI governance in counts. Never a compliance percentage. */
2226
+ export interface GovernanceSummary {
2227
+ aiSystems: number;
2228
+ production: number;
2229
+ elevatedOrHighRisk: number;
2230
+ governedTasks: number;
2231
+ outstandingControls: number;
2232
+ approvalsPending: number;
2233
+ expiredExceptions: number;
2234
+ openIncidents: number;
2235
+ tasksRequiringReview: number;
2236
+ systemsRequiringReview: number;
2237
+ tasks: {
2238
+ taskId: string;
2239
+ title: string;
2240
+ risk: GovernanceRisk;
2241
+ aiSystem: string | null;
2242
+ controls: { required: number; outstanding: number };
2243
+ reassessmentOpen: boolean;
2244
+ reviewOverdue: boolean;
2245
+ }[];
2246
+ filters: GovernanceSummaryInput;
2247
+ advancedFilters: boolean;
2248
+ }
2249
+
2250
+ /**
2251
+ * A governed task's evidence pack: profile, controls, evidence, task graph,
2252
+ * decisions, approvals and the audit timeline, with a digest. It assists
2253
+ * audit; it does not certify compliance. Every export is audited.
2254
+ */
2255
+ export interface GovernancePack {
2256
+ packKind: "ai_governance";
2257
+ packVersion: number;
2258
+ generatedAt: string;
2259
+ generatedBy: string;
2260
+ organisation: { id: string; name: string };
2261
+ statement: string;
2262
+ subject: { taskId: string; title: string; objective: string; url: string };
2263
+ aiSystem: AiSystem | null;
2264
+ profile: GovernanceProfileInput & { requiredByPolicy: boolean };
2265
+ readiness: GovernanceReadiness;
2266
+ gate: GovernanceGate;
2267
+ controls: GovernanceControl[];
2268
+ evidence: GovernanceEvidence[];
2269
+ frameworks: (GovernanceFramework & { requirements: RequirementCoverage[] })[];
2270
+ frameworkStatement: string | null;
2271
+ policies: Record<string, unknown>[];
2272
+ exceptions: Record<string, unknown>[];
2273
+ review: Record<string, unknown>;
2274
+ reassessments: Reassessment[];
2275
+ incidents: AiIncident[];
2276
+ thirdParty: Record<string, unknown> | null;
2277
+ doraReporting: Record<string, unknown>[];
2278
+ taskGraph: { id: string; parentTaskId: string | null; kind: string; title: string; status: string; outcome: string | null; result: string | null }[];
2279
+ findings: { taskId: string; kind: string; title: string; body: string; decisionStatus: string | null; decidedBy: string | null; recordedBy: string; at: string }[];
2280
+ approvals: { id: string; status: string; for: string }[];
2281
+ timeline: { at: string; event: string; actor: string; actorType: string; metadata: Record<string, unknown> }[];
2282
+ integrity: { algorithm: "sha256"; digest: string; covers: string; doesNotCover: string };
2283
+ }
2284
+
2285
+ export interface UpdateGovernanceProfileInput extends GovernanceProfileInput {
2286
+ /** The version you read; refused if somebody wrote in between. */
2287
+ expectedVersion?: number;
2288
+ }
2289
+
2290
+ export interface ControlApprovalInput {
2291
+ /** Emails, names or groups; the organisation's administrators when omitted. */
2292
+ approvers?: string[];
2293
+ note?: string;
2294
+ /** An ISO time. */
2295
+ expiresAt?: string;
2296
+ }
2297
+
2298
+ export interface ControlApprovalResult {
2299
+ governance: Governance;
2300
+ approvalId: string;
2301
+ approvalUrl: string;
2302
+ }
2303
+
1779
2304
  export interface ListTasksInput {
1780
2305
  /** A status, or `active` for anything not completed or cancelled. */
1781
2306
  status?: TaskStatus | "active";
@@ -1971,3 +2496,52 @@ export interface CallbackEnvelope {
1971
2496
  requestId: string;
1972
2497
  data: Record<string, unknown>;
1973
2498
  }
2499
+
2500
+ // ── Screening ──────────────────────────────────────────────────────────────
2501
+
2502
+ /** `allow` | `redact` | `ask` | `deny`: what may happen to text bound for a model. */
2503
+ export type ScreenVerdict = "allow" | "redact" | "ask" | "deny";
2504
+
2505
+ /** The AI register's record for the model the text is going to. */
2506
+ export interface ScreenTargetData {
2507
+ aiSystemId: string;
2508
+ name: string;
2509
+ /** The highest classification it is approved to receive; null when the record does not say. */
2510
+ approvedClassification: string | null;
2511
+ personalData: boolean;
2512
+ }
2513
+
2514
+ /** Where one finding is in the text you screened. Never its value. */
2515
+ export interface ScreenFindingData {
2516
+ kind: string;
2517
+ label: string;
2518
+ start: number;
2519
+ end: number;
2520
+ }
2521
+
2522
+ export interface ScreenApprovalRef {
2523
+ id: string;
2524
+ url: string;
2525
+ status: string;
2526
+ }
2527
+
2528
+ /** What `POST /screen` answers: the verdict, and why. */
2529
+ export interface ScreenData {
2530
+ verdict: ScreenVerdict;
2531
+ /** Whether the text may be sent now: as it is for `allow`, redacted for `redact`. */
2532
+ allowed: boolean;
2533
+ classification: "public" | "internal" | "confidential" | "restricted";
2534
+ personalData: boolean;
2535
+ categories: string[];
2536
+ /** What was found, by kind. */
2537
+ counts: Record<string, number>;
2538
+ /** The kinds behind the verdict: what redaction replaces. */
2539
+ offending: string[];
2540
+ reasons: string[];
2541
+ target: ScreenTargetData | null;
2542
+ /** Only when the server read the text. The SDK screens locally, so this is null from `screen()`. */
2543
+ findings: ScreenFindingData[] | null;
2544
+ redactedText: string | null;
2545
+ /** The approval a person decides, for an `ask` verdict. */
2546
+ approval: ScreenApprovalRef | null;
2547
+ }