@artemiskit/sdk 0.3.0 → 0.3.3

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 (74) hide show
  1. package/CHANGELOG.md +225 -0
  2. package/README.md +44 -1
  3. package/dist/artemiskit.d.ts +149 -0
  4. package/dist/artemiskit.d.ts.map +1 -0
  5. package/dist/builders/index.d.ts +350 -0
  6. package/dist/builders/index.d.ts.map +1 -0
  7. package/dist/builders/index.js +398 -0
  8. package/dist/contracts/index.d.ts +253 -0
  9. package/dist/contracts/index.d.ts.map +1 -0
  10. package/dist/contracts/index.js +99 -0
  11. package/dist/guardian/action-validator.d.ts +92 -0
  12. package/dist/guardian/action-validator.d.ts.map +1 -0
  13. package/dist/guardian/circuit-breaker.d.ts +211 -0
  14. package/dist/guardian/circuit-breaker.d.ts.map +1 -0
  15. package/dist/guardian/guardian.d.ts +213 -0
  16. package/dist/guardian/guardian.d.ts.map +1 -0
  17. package/dist/guardian/guardrails.d.ts +107 -0
  18. package/dist/guardian/guardrails.d.ts.map +1 -0
  19. package/dist/guardian/index.d.ts +35 -0
  20. package/dist/guardian/index.d.ts.map +1 -0
  21. package/dist/guardian/intent-classifier.d.ts +81 -0
  22. package/dist/guardian/intent-classifier.d.ts.map +1 -0
  23. package/dist/guardian/interceptor.d.ts +141 -0
  24. package/dist/guardian/interceptor.d.ts.map +1 -0
  25. package/dist/guardian/policy.d.ts +52 -0
  26. package/dist/guardian/policy.d.ts.map +1 -0
  27. package/dist/guardian/semantic-validator.d.ts +61 -0
  28. package/dist/guardian/semantic-validator.d.ts.map +1 -0
  29. package/dist/guardian/types.d.ts +653 -0
  30. package/dist/guardian/types.d.ts.map +1 -0
  31. package/dist/index.d.ts +23 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +24847 -13653
  34. package/dist/matchers/core.d.ts +81 -0
  35. package/dist/matchers/core.d.ts.map +1 -0
  36. package/dist/matchers/index.d.ts +6 -0
  37. package/dist/matchers/index.d.ts.map +1 -0
  38. package/dist/matchers/jest.d.ts +46 -0
  39. package/dist/matchers/jest.d.ts.map +1 -0
  40. package/dist/matchers/vitest.d.ts +24 -0
  41. package/dist/matchers/vitest.d.ts.map +1 -0
  42. package/dist/types-only.d.ts +31 -0
  43. package/dist/types-only.d.ts.map +1 -0
  44. package/dist/types-only.js +1 -0
  45. package/dist/types.d.ts +377 -0
  46. package/dist/types.d.ts.map +1 -0
  47. package/dist/utils/index.d.ts +112 -0
  48. package/dist/utils/index.d.ts.map +1 -0
  49. package/dist/utils/index.js +104 -0
  50. package/package.json +19 -4
  51. package/src/__tests__/builders.test.ts +445 -0
  52. package/src/__tests__/circuit-breaker.test.ts +704 -0
  53. package/src/__tests__/compare.test.ts +469 -0
  54. package/src/__tests__/contracts.test.ts +354 -0
  55. package/src/__tests__/guardian-modes.test.ts +215 -0
  56. package/src/__tests__/guardrails.test.ts +404 -0
  57. package/src/__tests__/semantic-validator.test.ts +421 -0
  58. package/src/__tests__/utils.test.ts +324 -0
  59. package/src/__tests__/validate.test.ts +307 -0
  60. package/src/artemiskit.ts +478 -5
  61. package/src/builders/index.ts +698 -0
  62. package/src/contracts/index.ts +357 -0
  63. package/src/guardian/circuit-breaker.ts +74 -28
  64. package/src/guardian/guardian.ts +307 -20
  65. package/src/guardian/guardrails.ts +143 -1
  66. package/src/guardian/index.ts +35 -1
  67. package/src/guardian/interceptor.ts +87 -11
  68. package/src/guardian/semantic-validator.ts +399 -0
  69. package/src/guardian/types.ts +413 -2
  70. package/src/index.ts +258 -14
  71. package/src/types-only.ts +276 -0
  72. package/src/types.ts +183 -0
  73. package/src/utils/index.ts +225 -0
  74. package/tsconfig.json +2 -1
@@ -0,0 +1,99 @@
1
+ // @bun
2
+ var __create = Object.create;
3
+ var __getProtoOf = Object.getPrototypeOf;
4
+ var __defProp = Object.defineProperty;
5
+ var __getOwnPropNames = Object.getOwnPropertyNames;
6
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
7
+ function __accessProp(key) {
8
+ return this[key];
9
+ }
10
+ var __toESMCache_node;
11
+ var __toESMCache_esm;
12
+ var __toESM = (mod, isNodeMode, target) => {
13
+ var canCache = mod != null && typeof mod === "object";
14
+ if (canCache) {
15
+ var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
16
+ var cached = cache.get(mod);
17
+ if (cached)
18
+ return cached;
19
+ }
20
+ target = mod != null ? __create(__getProtoOf(mod)) : {};
21
+ const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
22
+ for (let key of __getOwnPropNames(mod))
23
+ if (!__hasOwnProp.call(to, key))
24
+ __defProp(to, key, {
25
+ get: __accessProp.bind(mod, key),
26
+ enumerable: true
27
+ });
28
+ if (canCache)
29
+ cache.set(mod, to);
30
+ return to;
31
+ };
32
+ var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
33
+ var __returnValue = (v) => v;
34
+ function __exportSetter(name, newValue) {
35
+ this[name] = __returnValue.bind(null, newValue);
36
+ }
37
+ var __export = (target, all) => {
38
+ for (var name in all)
39
+ __defProp(target, name, {
40
+ get: all[name],
41
+ enumerable: true,
42
+ configurable: true,
43
+ set: __exportSetter.bind(all, name)
44
+ });
45
+ };
46
+ var __require = import.meta.require;
47
+
48
+ // src/contracts/index.ts
49
+ function defineAdapter(adapter) {
50
+ if (!adapter.provider) {
51
+ throw new Error("Adapter must have a provider property");
52
+ }
53
+ if (typeof adapter.generate !== "function") {
54
+ throw new Error("Adapter must have a generate method");
55
+ }
56
+ if (typeof adapter.capabilities !== "function") {
57
+ throw new Error("Adapter must have a capabilities method");
58
+ }
59
+ return adapter;
60
+ }
61
+ function defineEvaluator(evaluator) {
62
+ if (!evaluator.type) {
63
+ throw new Error("Evaluator must have a type property");
64
+ }
65
+ if (typeof evaluator.evaluate !== "function") {
66
+ throw new Error("Evaluator must have an evaluate method");
67
+ }
68
+ return evaluator;
69
+ }
70
+ function defineStorage(storage) {
71
+ if (typeof storage.save !== "function") {
72
+ throw new Error("Storage must have a save method");
73
+ }
74
+ if (typeof storage.load !== "function") {
75
+ throw new Error("Storage must have a load method");
76
+ }
77
+ if (typeof storage.list !== "function") {
78
+ throw new Error("Storage must have a list method");
79
+ }
80
+ if (typeof storage.delete !== "function") {
81
+ throw new Error("Storage must have a delete method");
82
+ }
83
+ return storage;
84
+ }
85
+ function definePlugin(plugin) {
86
+ if (!plugin.name) {
87
+ throw new Error("Plugin must have a name");
88
+ }
89
+ if (!plugin.version) {
90
+ throw new Error("Plugin must have a version");
91
+ }
92
+ return plugin;
93
+ }
94
+ export {
95
+ defineStorage,
96
+ definePlugin,
97
+ defineEvaluator,
98
+ defineAdapter
99
+ };
@@ -0,0 +1,92 @@
1
+ /**
2
+ * Action Validator
3
+ *
4
+ * Validates tool/function calls before execution.
5
+ * Ensures agents only perform allowed actions with valid parameters.
6
+ */
7
+ import type { ActionDefinition, GuardrailResult, InterceptedToolCall, Violation, ViolationSeverity } from './types';
8
+ /**
9
+ * Action validation result
10
+ */
11
+ export interface ActionValidationResult {
12
+ valid: boolean;
13
+ violations: Violation[];
14
+ sanitizedArguments?: Record<string, unknown>;
15
+ requiresApproval?: boolean;
16
+ }
17
+ /**
18
+ * Action validator configuration
19
+ */
20
+ export interface ActionValidatorConfig {
21
+ /** Allowed actions with their definitions */
22
+ allowedActions?: ActionDefinition[];
23
+ /** Default behavior for undefined actions */
24
+ defaultAllow?: boolean;
25
+ /** Default risk level for undefined actions */
26
+ defaultRiskLevel?: ViolationSeverity;
27
+ /** Block high-risk actions automatically */
28
+ blockHighRisk?: boolean;
29
+ /** Custom validation function */
30
+ customValidator?: (toolCall: InterceptedToolCall) => Promise<ActionValidationResult>;
31
+ }
32
+ /**
33
+ * Action Validator
34
+ *
35
+ * Validates tool/function calls against defined policies.
36
+ */
37
+ export declare class ActionValidator {
38
+ private config;
39
+ private actionMap;
40
+ private callHistory;
41
+ private callCounts;
42
+ constructor(config?: ActionValidatorConfig);
43
+ /**
44
+ * Validate a tool/function call
45
+ */
46
+ validate(toolCall: InterceptedToolCall): Promise<ActionValidationResult>;
47
+ /**
48
+ * Create a guardrail function from this validator
49
+ */
50
+ asGuardrail(): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
51
+ /**
52
+ * Register an allowed action
53
+ */
54
+ registerAction(action: ActionDefinition): void;
55
+ /**
56
+ * Remove an action from allowed list
57
+ */
58
+ unregisterAction(name: string): void;
59
+ /**
60
+ * Get all registered actions
61
+ */
62
+ getRegisteredActions(): ActionDefinition[];
63
+ /**
64
+ * Get call history
65
+ */
66
+ getCallHistory(): InterceptedToolCall[];
67
+ /**
68
+ * Clear call history
69
+ */
70
+ clearHistory(): void;
71
+ /**
72
+ * Check rate limit for an action
73
+ */
74
+ private checkRateLimit;
75
+ /**
76
+ * Validate parameters against definitions
77
+ */
78
+ private validateParameters;
79
+ /**
80
+ * Check if value matches expected type
81
+ */
82
+ private checkType;
83
+ /**
84
+ * Run validation rules on a parameter value
85
+ */
86
+ private runValidation;
87
+ }
88
+ /**
89
+ * Create a pre-configured action validator with common dangerous actions blocked
90
+ */
91
+ export declare function createDefaultActionValidator(): ActionValidator;
92
+ //# sourceMappingURL=action-validator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"action-validator.d.ts","sourceRoot":"","sources":["../../src/guardian/action-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAEhB,eAAe,EACf,mBAAmB,EAEnB,SAAS,EACT,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACpC,6CAA6C;IAC7C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,4CAA4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iCAAiC;IACjC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACtF;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,UAAU,CAAsD;gBAE5D,MAAM,GAAE,qBAA0B;IAmB9C;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAqG9E;;OAEG;IACH,WAAW,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC;IAiB/F;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAI9C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,oBAAoB,IAAI,gBAAgB,EAAE;IAI1C;;OAEG;IACH,cAAc,IAAI,mBAAmB,EAAE;IAIvC;;OAEG;IACH,YAAY,IAAI,IAAI;IAKpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAsCtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwD1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAiBjB;;OAEG;IACH,OAAO,CAAC,aAAa;CAsItB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAwF9D"}
@@ -0,0 +1,211 @@
1
+ /**
2
+ * Circuit Breaker and Metrics
3
+ *
4
+ * Implements the circuit breaker pattern to protect against repeated failures
5
+ * and provides comprehensive metrics tracking for guardian operations.
6
+ */
7
+ import type { CircuitBreakerConfig, CircuitBreakerState, GuardianMetrics, Violation } from './types';
8
+ /**
9
+ * Circuit breaker event types
10
+ */
11
+ export type CircuitBreakerEvent = 'open' | 'close' | 'half-open' | 'violation' | 'success';
12
+ /**
13
+ * Circuit breaker event handler
14
+ */
15
+ export type CircuitBreakerEventHandler = (event: CircuitBreakerEvent, data?: Record<string, unknown>) => void;
16
+ /**
17
+ * Circuit Breaker implementation
18
+ *
19
+ * Protects against cascading failures by opening the circuit
20
+ * when too many violations occur within a time window.
21
+ */
22
+ export declare class CircuitBreaker {
23
+ private config;
24
+ private state;
25
+ private violations;
26
+ private lastOpenTime;
27
+ private halfOpenSuccesses;
28
+ private eventHandlers;
29
+ constructor(config: CircuitBreakerConfig);
30
+ /**
31
+ * Check if the circuit is open (requests should be blocked)
32
+ */
33
+ isOpen(): boolean;
34
+ /**
35
+ * Check if the circuit allows requests
36
+ * @deprecated Use isOpen() instead - this method duplicates functionality.
37
+ * Guardian uses isOpen() exclusively for circuit breaker checks.
38
+ */
39
+ allowRequest(): boolean;
40
+ /**
41
+ * Record a violation
42
+ */
43
+ recordViolation(violation: Violation): void;
44
+ /**
45
+ * Record a successful request (no violations)
46
+ */
47
+ recordSuccess(): void;
48
+ /**
49
+ * Trip the circuit breaker (open it)
50
+ */
51
+ trip(): void;
52
+ /**
53
+ * Reset the circuit breaker (close it)
54
+ */
55
+ reset(): void;
56
+ /**
57
+ * Force the circuit to a specific state.
58
+ * When forcing to 'open', also updates lastOpenTime so the cooldown
59
+ * period starts from now (matching trip() behavior).
60
+ */
61
+ forceState(state: CircuitBreakerState): void;
62
+ /**
63
+ * Get the current state
64
+ */
65
+ getState(): CircuitBreakerState;
66
+ /**
67
+ * Get violation count in current window
68
+ */
69
+ getViolationCount(): number;
70
+ /**
71
+ * Get time until the circuit breaker resets (if open)
72
+ */
73
+ getTimeUntilReset(): number;
74
+ /**
75
+ * Register an event handler
76
+ */
77
+ onEvent(handler: CircuitBreakerEventHandler): void;
78
+ /**
79
+ * Remove an event handler
80
+ */
81
+ offEvent(handler: CircuitBreakerEventHandler): void;
82
+ /**
83
+ * Transition to a new state
84
+ */
85
+ private transition;
86
+ /**
87
+ * Emit an event to all handlers
88
+ */
89
+ private emit;
90
+ }
91
+ /**
92
+ * Metrics collector for guardian operations
93
+ */
94
+ export declare class MetricsCollector {
95
+ private currentWindow;
96
+ private windowDurationMs;
97
+ private history;
98
+ private maxHistoryWindows;
99
+ private currency;
100
+ constructor(options?: {
101
+ windowDurationMs?: number;
102
+ maxHistoryWindows?: number;
103
+ currency?: string;
104
+ });
105
+ /**
106
+ * Record a request
107
+ */
108
+ recordRequest(options: {
109
+ blocked: boolean;
110
+ warned: boolean;
111
+ latencyMs: number;
112
+ violations: Violation[];
113
+ cost?: number;
114
+ }): void;
115
+ /**
116
+ * Get current metrics
117
+ */
118
+ getMetrics(circuitBreakerState?: CircuitBreakerState): GuardianMetrics;
119
+ /**
120
+ * Get metrics for the current window only
121
+ */
122
+ getCurrentWindowMetrics(): Partial<GuardianMetrics>;
123
+ /**
124
+ * Reset all metrics
125
+ */
126
+ reset(): void;
127
+ /**
128
+ * Get cost per minute (actual rate based on elapsed time)
129
+ *
130
+ * To avoid extreme extrapolated values immediately after window rotation,
131
+ * we require a minimum duration of data before extrapolating. If insufficient
132
+ * data is available in the current window, we fall back to historical data.
133
+ */
134
+ private getCostPerMinute;
135
+ /**
136
+ * Get hourly cost
137
+ */
138
+ private getHourlyCost;
139
+ /**
140
+ * Get daily cost (estimated based on available data)
141
+ */
142
+ private getDailyCost;
143
+ /**
144
+ * Create a new metrics window
145
+ */
146
+ private createWindow;
147
+ /**
148
+ * Rotate to a new window if needed
149
+ */
150
+ private rotateWindowIfNeeded;
151
+ }
152
+ /**
153
+ * Rate limiter configuration
154
+ */
155
+ export interface RateLimiterConfig {
156
+ requestsPerMinute?: number;
157
+ requestsPerHour?: number;
158
+ requestsPerDay?: number;
159
+ burstLimit?: number;
160
+ }
161
+ /**
162
+ * Token bucket rate limiter
163
+ */
164
+ export declare class RateLimiter {
165
+ private config;
166
+ private minuteWindow;
167
+ private hourWindow;
168
+ private dayWindow;
169
+ private burstTokens;
170
+ private lastBurstRefill;
171
+ constructor(config: RateLimiterConfig);
172
+ /**
173
+ * Check if a request is allowed
174
+ */
175
+ allowRequest(): {
176
+ allowed: boolean;
177
+ reason?: string;
178
+ retryAfterMs?: number;
179
+ };
180
+ /**
181
+ * Get current rate limit status
182
+ */
183
+ getStatus(): {
184
+ minuteUsed: number;
185
+ minuteLimit?: number;
186
+ hourUsed: number;
187
+ hourLimit?: number;
188
+ dayUsed: number;
189
+ dayLimit?: number;
190
+ burstTokens: number;
191
+ burstLimit?: number;
192
+ };
193
+ /**
194
+ * Reset all rate limits
195
+ */
196
+ reset(): void;
197
+ /**
198
+ * Refill burst tokens
199
+ */
200
+ private refillBurstTokens;
201
+ /**
202
+ * Rotate time windows using sliding window approximation.
203
+ *
204
+ * To prevent the fixed-window burst vulnerability (allowing 2× the limit at
205
+ * window boundaries), we use a sliding window approximation: when a window
206
+ * rotates, we carry over a proportional count from the previous window based
207
+ * on how much of the new window overlaps with the old one.
208
+ */
209
+ private rotateWindows;
210
+ }
211
+ //# sourceMappingURL=circuit-breaker.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/guardian/circuit-breaker.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,213 @@
1
+ /**
2
+ * Guardian - Main runtime protection class
3
+ *
4
+ * Provides a unified interface for all guardian features:
5
+ * - Interceptor for LLM client wrapping
6
+ * - Action validation for tool/function calls
7
+ * - Intent classification
8
+ * - Input/output guardrails
9
+ * - Policy-based configuration
10
+ * - Circuit breaker protection
11
+ * - Metrics collection
12
+ */
13
+ import type { ModelClient } from '@artemiskit/core';
14
+ import { RateLimiter } from './circuit-breaker';
15
+ import { type GuardrailsConfig } from './guardrails';
16
+ import { GuardianBlockedError, GuardianInterceptor, type GuardrailFn } from './interceptor';
17
+ import type { ActionDefinition, ContentValidationConfig, GuardianEventHandler, GuardianMetrics, GuardianMode, GuardianModeCanonical, GuardianPolicy, MultiTurnConfig, Violation } from './types';
18
+ /**
19
+ * Normalize Guardian mode to canonical form with deprecation warning
20
+ * @param mode - The mode to normalize
21
+ * @returns The canonical mode
22
+ */
23
+ export declare function normalizeGuardianMode(mode: GuardianMode): GuardianModeCanonical;
24
+ /**
25
+ * Guardian configuration options
26
+ */
27
+ export interface GuardianConfig {
28
+ /**
29
+ * Operating mode
30
+ *
31
+ * Canonical modes (recommended):
32
+ * - 'observe': Log only, never block (for monitoring)
33
+ * - 'selective': Block high-confidence threats (threshold-based)
34
+ * - 'strict': Block all detected violations (maximum protection)
35
+ *
36
+ * Legacy modes (deprecated):
37
+ * - 'testing' → 'observe'
38
+ * - 'guardian' → 'strict'
39
+ * - 'hybrid' → 'selective'
40
+ */
41
+ mode?: GuardianMode;
42
+ /** Policy file path or policy object */
43
+ policy?: string | GuardianPolicy;
44
+ /** LLM client for semantic validation and intent classification */
45
+ llmClient?: ModelClient;
46
+ /** Enable input validation */
47
+ validateInput?: boolean;
48
+ /** Enable output validation */
49
+ validateOutput?: boolean;
50
+ /** Block on validation failure */
51
+ blockOnFailure?: boolean;
52
+ /**
53
+ * Content validation strategy configuration
54
+ *
55
+ * @default { strategy: 'semantic', semanticThreshold: 0.9 }
56
+ */
57
+ contentValidation?: ContentValidationConfig;
58
+ /** Custom guardrails configuration (pattern-based) */
59
+ guardrails?: GuardrailsConfig;
60
+ /**
61
+ * Multi-turn detection configuration
62
+ *
63
+ * Enable to detect attacks that span multiple messages:
64
+ * - Trust-building before sensitive requests
65
+ * - Escalating risk patterns
66
+ * - Context manipulation claims
67
+ * - Split payload attacks
68
+ */
69
+ multiTurn?: MultiTurnConfig;
70
+ /** Custom action definitions */
71
+ allowedActions?: ActionDefinition[];
72
+ /** Event handler */
73
+ onEvent?: GuardianEventHandler;
74
+ /** Enable metrics collection */
75
+ collectMetrics?: boolean;
76
+ /** Enable logging */
77
+ enableLogging?: boolean;
78
+ }
79
+ /**
80
+ * Guardian class - main runtime protection API
81
+ */
82
+ export declare class Guardian {
83
+ private config;
84
+ private policy;
85
+ private circuitBreaker;
86
+ private rateLimiter?;
87
+ private metricsCollector;
88
+ private actionValidator;
89
+ private intentClassifier;
90
+ private semanticValidator?;
91
+ private inputGuardrails;
92
+ private outputGuardrails;
93
+ private eventHandlers;
94
+ /** The normalized (canonical) mode after processing legacy modes */
95
+ private normalizedMode;
96
+ constructor(config?: GuardianConfig);
97
+ /**
98
+ * Wrap a model client with guardian protection
99
+ *
100
+ * Note: Checks circuit breaker on each LLM request via the shouldAllow callback.
101
+ * When the circuit is open due to detected attack patterns, all LLM requests are blocked.
102
+ */
103
+ protect(client: ModelClient): GuardianInterceptor;
104
+ /**
105
+ * Validate a tool/function call
106
+ */
107
+ validateAction(toolName: string, args: Record<string, unknown>, agentId?: string): Promise<{
108
+ valid: boolean;
109
+ violations: Violation[];
110
+ sanitizedArguments?: Record<string, unknown>;
111
+ requiresApproval?: boolean;
112
+ }>;
113
+ /**
114
+ * Classify intent of a message
115
+ */
116
+ classifyIntent(text: string): Promise<import("./types").IntentClassification[]>;
117
+ /**
118
+ * Validate input content
119
+ */
120
+ validateInput(content: string): Promise<{
121
+ valid: boolean;
122
+ violations: Violation[];
123
+ transformedContent?: string;
124
+ }>;
125
+ /**
126
+ * Validate output content
127
+ */
128
+ validateOutput(content: string): Promise<{
129
+ valid: boolean;
130
+ violations: Violation[];
131
+ transformedContent?: string;
132
+ }>;
133
+ /**
134
+ * Get current metrics
135
+ */
136
+ getMetrics(): GuardianMetrics;
137
+ /**
138
+ * Get circuit breaker state
139
+ */
140
+ getCircuitBreakerState(): {
141
+ state: string;
142
+ violationCount: number;
143
+ timeUntilReset: number;
144
+ };
145
+ /**
146
+ * Get rate limit status
147
+ */
148
+ getRateLimitStatus(): ReturnType<RateLimiter['getStatus']> | undefined;
149
+ /**
150
+ * Get the current policy
151
+ */
152
+ getPolicy(): GuardianPolicy;
153
+ /**
154
+ * Get the normalized (canonical) operating mode
155
+ *
156
+ * This returns the canonical mode even if a legacy mode was configured.
157
+ */
158
+ getMode(): GuardianModeCanonical;
159
+ /**
160
+ * Check if Guardian should block based on mode and violation severity
161
+ *
162
+ * - observe: Never blocks
163
+ * - selective: Blocks high-confidence/high-severity only
164
+ * - strict: Blocks all violations
165
+ */
166
+ shouldBlock(violation: Violation): boolean;
167
+ /**
168
+ * Get the content validation configuration
169
+ */
170
+ getContentValidationConfig(): ContentValidationConfig;
171
+ /**
172
+ * Update policy at runtime
173
+ */
174
+ updatePolicy(policy: GuardianPolicy): void;
175
+ /**
176
+ * Register an allowed action
177
+ */
178
+ registerAction(action: ActionDefinition): void;
179
+ /**
180
+ * Add a custom guardrail
181
+ */
182
+ addInputGuardrail(guardrail: GuardrailFn): void;
183
+ /**
184
+ * Add a custom output guardrail
185
+ */
186
+ addOutputGuardrail(guardrail: GuardrailFn): void;
187
+ /**
188
+ * Register an event handler
189
+ */
190
+ onEvent(handler: GuardianEventHandler): void;
191
+ /**
192
+ * Remove an event handler
193
+ */
194
+ offEvent(handler: GuardianEventHandler): void;
195
+ /**
196
+ * Reset all metrics and state
197
+ */
198
+ reset(): void;
199
+ /**
200
+ * Load or create policy
201
+ */
202
+ private loadOrCreatePolicy;
203
+ /**
204
+ * Emit an event to all handlers
205
+ */
206
+ private emit;
207
+ }
208
+ /**
209
+ * Create a guardian instance
210
+ */
211
+ export declare function createGuardian(config?: GuardianConfig): Guardian;
212
+ export { GuardianBlockedError };
213
+ //# sourceMappingURL=guardian.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guardian.d.ts","sourceRoot":"","sources":["../../src/guardian/guardian.ts"],"names":[],"mappings":"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"}