@lleverage-ai/agent-sdk 0.0.1

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 (327) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2321 -0
  3. package/dist/agent.d.ts +52 -0
  4. package/dist/agent.d.ts.map +1 -0
  5. package/dist/agent.js +2122 -0
  6. package/dist/agent.js.map +1 -0
  7. package/dist/backend.d.ts +378 -0
  8. package/dist/backend.d.ts.map +1 -0
  9. package/dist/backend.js +71 -0
  10. package/dist/backend.js.map +1 -0
  11. package/dist/backends/composite.d.ts +258 -0
  12. package/dist/backends/composite.d.ts.map +1 -0
  13. package/dist/backends/composite.js +437 -0
  14. package/dist/backends/composite.js.map +1 -0
  15. package/dist/backends/filesystem.d.ts +268 -0
  16. package/dist/backends/filesystem.d.ts.map +1 -0
  17. package/dist/backends/filesystem.js +623 -0
  18. package/dist/backends/filesystem.js.map +1 -0
  19. package/dist/backends/index.d.ts +14 -0
  20. package/dist/backends/index.d.ts.map +1 -0
  21. package/dist/backends/index.js +14 -0
  22. package/dist/backends/index.js.map +1 -0
  23. package/dist/backends/persistent.d.ts +312 -0
  24. package/dist/backends/persistent.d.ts.map +1 -0
  25. package/dist/backends/persistent.js +519 -0
  26. package/dist/backends/persistent.js.map +1 -0
  27. package/dist/backends/sandbox.d.ts +315 -0
  28. package/dist/backends/sandbox.d.ts.map +1 -0
  29. package/dist/backends/sandbox.js +490 -0
  30. package/dist/backends/sandbox.js.map +1 -0
  31. package/dist/backends/state.d.ts +225 -0
  32. package/dist/backends/state.d.ts.map +1 -0
  33. package/dist/backends/state.js +396 -0
  34. package/dist/backends/state.js.map +1 -0
  35. package/dist/checkpointer/file-saver.d.ts +182 -0
  36. package/dist/checkpointer/file-saver.d.ts.map +1 -0
  37. package/dist/checkpointer/file-saver.js +298 -0
  38. package/dist/checkpointer/file-saver.js.map +1 -0
  39. package/dist/checkpointer/index.d.ts +40 -0
  40. package/dist/checkpointer/index.d.ts.map +1 -0
  41. package/dist/checkpointer/index.js +40 -0
  42. package/dist/checkpointer/index.js.map +1 -0
  43. package/dist/checkpointer/kv-saver.d.ts +142 -0
  44. package/dist/checkpointer/kv-saver.d.ts.map +1 -0
  45. package/dist/checkpointer/kv-saver.js +176 -0
  46. package/dist/checkpointer/kv-saver.js.map +1 -0
  47. package/dist/checkpointer/memory-saver.d.ts +158 -0
  48. package/dist/checkpointer/memory-saver.d.ts.map +1 -0
  49. package/dist/checkpointer/memory-saver.js +222 -0
  50. package/dist/checkpointer/memory-saver.js.map +1 -0
  51. package/dist/checkpointer/types.d.ts +353 -0
  52. package/dist/checkpointer/types.d.ts.map +1 -0
  53. package/dist/checkpointer/types.js +159 -0
  54. package/dist/checkpointer/types.js.map +1 -0
  55. package/dist/context-manager.d.ts +627 -0
  56. package/dist/context-manager.d.ts.map +1 -0
  57. package/dist/context-manager.js +1039 -0
  58. package/dist/context-manager.js.map +1 -0
  59. package/dist/context.d.ts +57 -0
  60. package/dist/context.d.ts.map +1 -0
  61. package/dist/context.js +76 -0
  62. package/dist/context.js.map +1 -0
  63. package/dist/errors/index.d.ts +611 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/index.js +1023 -0
  66. package/dist/errors/index.js.map +1 -0
  67. package/dist/generation-helpers.d.ts +126 -0
  68. package/dist/generation-helpers.d.ts.map +1 -0
  69. package/dist/generation-helpers.js +181 -0
  70. package/dist/generation-helpers.js.map +1 -0
  71. package/dist/hooks/audit.d.ts +210 -0
  72. package/dist/hooks/audit.d.ts.map +1 -0
  73. package/dist/hooks/audit.js +305 -0
  74. package/dist/hooks/audit.js.map +1 -0
  75. package/dist/hooks/cache.d.ts +180 -0
  76. package/dist/hooks/cache.d.ts.map +1 -0
  77. package/dist/hooks/cache.js +273 -0
  78. package/dist/hooks/cache.js.map +1 -0
  79. package/dist/hooks/guardrails.d.ts +145 -0
  80. package/dist/hooks/guardrails.d.ts.map +1 -0
  81. package/dist/hooks/guardrails.js +326 -0
  82. package/dist/hooks/guardrails.js.map +1 -0
  83. package/dist/hooks/index.d.ts +18 -0
  84. package/dist/hooks/index.d.ts.map +1 -0
  85. package/dist/hooks/index.js +32 -0
  86. package/dist/hooks/index.js.map +1 -0
  87. package/dist/hooks/logging.d.ts +193 -0
  88. package/dist/hooks/logging.d.ts.map +1 -0
  89. package/dist/hooks/logging.js +345 -0
  90. package/dist/hooks/logging.js.map +1 -0
  91. package/dist/hooks/parallel-guardrails.d.ts +268 -0
  92. package/dist/hooks/parallel-guardrails.d.ts.map +1 -0
  93. package/dist/hooks/parallel-guardrails.js +416 -0
  94. package/dist/hooks/parallel-guardrails.js.map +1 -0
  95. package/dist/hooks/rate-limit.d.ts +305 -0
  96. package/dist/hooks/rate-limit.d.ts.map +1 -0
  97. package/dist/hooks/rate-limit.js +372 -0
  98. package/dist/hooks/rate-limit.js.map +1 -0
  99. package/dist/hooks/retry.d.ts +144 -0
  100. package/dist/hooks/retry.d.ts.map +1 -0
  101. package/dist/hooks/retry.js +210 -0
  102. package/dist/hooks/retry.js.map +1 -0
  103. package/dist/hooks/secrets.d.ts +174 -0
  104. package/dist/hooks/secrets.d.ts.map +1 -0
  105. package/dist/hooks/secrets.js +306 -0
  106. package/dist/hooks/secrets.js.map +1 -0
  107. package/dist/hooks.d.ts +229 -0
  108. package/dist/hooks.d.ts.map +1 -0
  109. package/dist/hooks.js +352 -0
  110. package/dist/hooks.js.map +1 -0
  111. package/dist/index.d.ts +97 -0
  112. package/dist/index.d.ts.map +1 -0
  113. package/dist/index.js +182 -0
  114. package/dist/index.js.map +1 -0
  115. package/dist/mcp/env.d.ts +25 -0
  116. package/dist/mcp/env.d.ts.map +1 -0
  117. package/dist/mcp/env.js +18 -0
  118. package/dist/mcp/env.js.map +1 -0
  119. package/dist/mcp/index.d.ts +16 -0
  120. package/dist/mcp/index.d.ts.map +1 -0
  121. package/dist/mcp/index.js +17 -0
  122. package/dist/mcp/index.js.map +1 -0
  123. package/dist/mcp/manager.d.ts +184 -0
  124. package/dist/mcp/manager.d.ts.map +1 -0
  125. package/dist/mcp/manager.js +446 -0
  126. package/dist/mcp/manager.js.map +1 -0
  127. package/dist/mcp/types.d.ts +58 -0
  128. package/dist/mcp/types.d.ts.map +1 -0
  129. package/dist/mcp/types.js +7 -0
  130. package/dist/mcp/types.js.map +1 -0
  131. package/dist/mcp/validation.d.ts +119 -0
  132. package/dist/mcp/validation.d.ts.map +1 -0
  133. package/dist/mcp/validation.js +407 -0
  134. package/dist/mcp/validation.js.map +1 -0
  135. package/dist/mcp/virtual-server.d.ts +78 -0
  136. package/dist/mcp/virtual-server.d.ts.map +1 -0
  137. package/dist/mcp/virtual-server.js +137 -0
  138. package/dist/mcp/virtual-server.js.map +1 -0
  139. package/dist/memory/filesystem-store.d.ts +217 -0
  140. package/dist/memory/filesystem-store.d.ts.map +1 -0
  141. package/dist/memory/filesystem-store.js +343 -0
  142. package/dist/memory/filesystem-store.js.map +1 -0
  143. package/dist/memory/index.d.ts +46 -0
  144. package/dist/memory/index.d.ts.map +1 -0
  145. package/dist/memory/index.js +46 -0
  146. package/dist/memory/index.js.map +1 -0
  147. package/dist/memory/loader.d.ts +396 -0
  148. package/dist/memory/loader.d.ts.map +1 -0
  149. package/dist/memory/loader.js +419 -0
  150. package/dist/memory/loader.js.map +1 -0
  151. package/dist/memory/permissions.d.ts +282 -0
  152. package/dist/memory/permissions.d.ts.map +1 -0
  153. package/dist/memory/permissions.js +297 -0
  154. package/dist/memory/permissions.js.map +1 -0
  155. package/dist/memory/rules.d.ts +249 -0
  156. package/dist/memory/rules.d.ts.map +1 -0
  157. package/dist/memory/rules.js +362 -0
  158. package/dist/memory/rules.js.map +1 -0
  159. package/dist/memory/store.d.ts +286 -0
  160. package/dist/memory/store.d.ts.map +1 -0
  161. package/dist/memory/store.js +263 -0
  162. package/dist/memory/store.js.map +1 -0
  163. package/dist/middleware/apply.d.ts +73 -0
  164. package/dist/middleware/apply.d.ts.map +1 -0
  165. package/dist/middleware/apply.js +219 -0
  166. package/dist/middleware/apply.js.map +1 -0
  167. package/dist/middleware/context.d.ts +33 -0
  168. package/dist/middleware/context.d.ts.map +1 -0
  169. package/dist/middleware/context.js +176 -0
  170. package/dist/middleware/context.js.map +1 -0
  171. package/dist/middleware/index.d.ts +31 -0
  172. package/dist/middleware/index.d.ts.map +1 -0
  173. package/dist/middleware/index.js +32 -0
  174. package/dist/middleware/index.js.map +1 -0
  175. package/dist/middleware/logging.d.ts +137 -0
  176. package/dist/middleware/logging.d.ts.map +1 -0
  177. package/dist/middleware/logging.js +374 -0
  178. package/dist/middleware/logging.js.map +1 -0
  179. package/dist/middleware/types.d.ts +183 -0
  180. package/dist/middleware/types.d.ts.map +1 -0
  181. package/dist/middleware/types.js +11 -0
  182. package/dist/middleware/types.js.map +1 -0
  183. package/dist/observability/events.d.ts +183 -0
  184. package/dist/observability/events.d.ts.map +1 -0
  185. package/dist/observability/events.js +305 -0
  186. package/dist/observability/events.js.map +1 -0
  187. package/dist/observability/index.d.ts +55 -0
  188. package/dist/observability/index.d.ts.map +1 -0
  189. package/dist/observability/index.js +87 -0
  190. package/dist/observability/index.js.map +1 -0
  191. package/dist/observability/logger.d.ts +318 -0
  192. package/dist/observability/logger.d.ts.map +1 -0
  193. package/dist/observability/logger.js +436 -0
  194. package/dist/observability/logger.js.map +1 -0
  195. package/dist/observability/metrics.d.ts +341 -0
  196. package/dist/observability/metrics.d.ts.map +1 -0
  197. package/dist/observability/metrics.js +490 -0
  198. package/dist/observability/metrics.js.map +1 -0
  199. package/dist/observability/preset.d.ts +161 -0
  200. package/dist/observability/preset.d.ts.map +1 -0
  201. package/dist/observability/preset.js +133 -0
  202. package/dist/observability/preset.js.map +1 -0
  203. package/dist/observability/streaming.d.ts +113 -0
  204. package/dist/observability/streaming.d.ts.map +1 -0
  205. package/dist/observability/streaming.js +114 -0
  206. package/dist/observability/streaming.js.map +1 -0
  207. package/dist/observability/tracing.d.ts +378 -0
  208. package/dist/observability/tracing.d.ts.map +1 -0
  209. package/dist/observability/tracing.js +539 -0
  210. package/dist/observability/tracing.js.map +1 -0
  211. package/dist/plugins.d.ts +55 -0
  212. package/dist/plugins.d.ts.map +1 -0
  213. package/dist/plugins.js +63 -0
  214. package/dist/plugins.js.map +1 -0
  215. package/dist/presets/index.d.ts +7 -0
  216. package/dist/presets/index.d.ts.map +1 -0
  217. package/dist/presets/index.js +7 -0
  218. package/dist/presets/index.js.map +1 -0
  219. package/dist/presets/production.d.ts +262 -0
  220. package/dist/presets/production.d.ts.map +1 -0
  221. package/dist/presets/production.js +295 -0
  222. package/dist/presets/production.js.map +1 -0
  223. package/dist/security/index.d.ts +179 -0
  224. package/dist/security/index.d.ts.map +1 -0
  225. package/dist/security/index.js +323 -0
  226. package/dist/security/index.js.map +1 -0
  227. package/dist/subagents/advanced.d.ts +413 -0
  228. package/dist/subagents/advanced.d.ts.map +1 -0
  229. package/dist/subagents/advanced.js +396 -0
  230. package/dist/subagents/advanced.js.map +1 -0
  231. package/dist/subagents/index.d.ts +14 -0
  232. package/dist/subagents/index.d.ts.map +1 -0
  233. package/dist/subagents/index.js +15 -0
  234. package/dist/subagents/index.js.map +1 -0
  235. package/dist/subagents.d.ts +73 -0
  236. package/dist/subagents.d.ts.map +1 -0
  237. package/dist/subagents.js +213 -0
  238. package/dist/subagents.js.map +1 -0
  239. package/dist/task-store/file-store.d.ts +76 -0
  240. package/dist/task-store/file-store.d.ts.map +1 -0
  241. package/dist/task-store/file-store.js +190 -0
  242. package/dist/task-store/file-store.js.map +1 -0
  243. package/dist/task-store/index.d.ts +11 -0
  244. package/dist/task-store/index.d.ts.map +1 -0
  245. package/dist/task-store/index.js +10 -0
  246. package/dist/task-store/index.js.map +1 -0
  247. package/dist/task-store/kv-store.d.ts +140 -0
  248. package/dist/task-store/kv-store.d.ts.map +1 -0
  249. package/dist/task-store/kv-store.js +169 -0
  250. package/dist/task-store/kv-store.js.map +1 -0
  251. package/dist/task-store/memory-store.d.ts +66 -0
  252. package/dist/task-store/memory-store.d.ts.map +1 -0
  253. package/dist/task-store/memory-store.js +125 -0
  254. package/dist/task-store/memory-store.js.map +1 -0
  255. package/dist/task-store/types.d.ts +235 -0
  256. package/dist/task-store/types.d.ts.map +1 -0
  257. package/dist/task-store/types.js +110 -0
  258. package/dist/task-store/types.js.map +1 -0
  259. package/dist/testing/assertions.d.ts +401 -0
  260. package/dist/testing/assertions.d.ts.map +1 -0
  261. package/dist/testing/assertions.js +630 -0
  262. package/dist/testing/assertions.js.map +1 -0
  263. package/dist/testing/index.d.ts +343 -0
  264. package/dist/testing/index.d.ts.map +1 -0
  265. package/dist/testing/index.js +360 -0
  266. package/dist/testing/index.js.map +1 -0
  267. package/dist/testing/mock-agent.d.ts +214 -0
  268. package/dist/testing/mock-agent.d.ts.map +1 -0
  269. package/dist/testing/mock-agent.js +448 -0
  270. package/dist/testing/mock-agent.js.map +1 -0
  271. package/dist/testing/recorder.d.ts +288 -0
  272. package/dist/testing/recorder.d.ts.map +1 -0
  273. package/dist/testing/recorder.js +499 -0
  274. package/dist/testing/recorder.js.map +1 -0
  275. package/dist/tools/execute.d.ts +104 -0
  276. package/dist/tools/execute.d.ts.map +1 -0
  277. package/dist/tools/execute.js +191 -0
  278. package/dist/tools/execute.js.map +1 -0
  279. package/dist/tools/factory.d.ts +260 -0
  280. package/dist/tools/factory.d.ts.map +1 -0
  281. package/dist/tools/factory.js +241 -0
  282. package/dist/tools/factory.js.map +1 -0
  283. package/dist/tools/filesystem.d.ts +215 -0
  284. package/dist/tools/filesystem.d.ts.map +1 -0
  285. package/dist/tools/filesystem.js +311 -0
  286. package/dist/tools/filesystem.js.map +1 -0
  287. package/dist/tools/index.d.ts +33 -0
  288. package/dist/tools/index.d.ts.map +1 -0
  289. package/dist/tools/index.js +33 -0
  290. package/dist/tools/index.js.map +1 -0
  291. package/dist/tools/search.d.ts +59 -0
  292. package/dist/tools/search.d.ts.map +1 -0
  293. package/dist/tools/search.js +94 -0
  294. package/dist/tools/search.js.map +1 -0
  295. package/dist/tools/skills.d.ts +354 -0
  296. package/dist/tools/skills.d.ts.map +1 -0
  297. package/dist/tools/skills.js +413 -0
  298. package/dist/tools/skills.js.map +1 -0
  299. package/dist/tools/task.d.ts +272 -0
  300. package/dist/tools/task.d.ts.map +1 -0
  301. package/dist/tools/task.js +521 -0
  302. package/dist/tools/task.js.map +1 -0
  303. package/dist/tools/todos.d.ts +131 -0
  304. package/dist/tools/todos.d.ts.map +1 -0
  305. package/dist/tools/todos.js +120 -0
  306. package/dist/tools/todos.js.map +1 -0
  307. package/dist/tools/tool-registry.d.ts +424 -0
  308. package/dist/tools/tool-registry.d.ts.map +1 -0
  309. package/dist/tools/tool-registry.js +607 -0
  310. package/dist/tools/tool-registry.js.map +1 -0
  311. package/dist/tools/user-interaction.d.ts +116 -0
  312. package/dist/tools/user-interaction.d.ts.map +1 -0
  313. package/dist/tools/user-interaction.js +147 -0
  314. package/dist/tools/user-interaction.js.map +1 -0
  315. package/dist/tools/utils.d.ts +124 -0
  316. package/dist/tools/utils.d.ts.map +1 -0
  317. package/dist/tools/utils.js +189 -0
  318. package/dist/tools/utils.js.map +1 -0
  319. package/dist/tools.d.ts +74 -0
  320. package/dist/tools.d.ts.map +1 -0
  321. package/dist/tools.js +73 -0
  322. package/dist/tools.js.map +1 -0
  323. package/dist/types.d.ts +2421 -0
  324. package/dist/types.d.ts.map +1 -0
  325. package/dist/types.js +55 -0
  326. package/dist/types.js.map +1 -0
  327. package/package.json +81 -0
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Security policy presets for agent configuration.
3
+ *
4
+ * This module provides security policy presets that bundle together sandbox configuration,
5
+ * permission modes, and hook settings to enforce different security levels. The presets help
6
+ * developers quickly configure agents for different environments (development, CI, production)
7
+ * without manually configuring each security control.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * import { createAgent } from "@lleverage-ai/agent-sdk";
12
+ * import { applySecurityPolicy, SecurityPolicyPreset } from "@lleverage-ai/agent-sdk/security";
13
+ *
14
+ * // Create an agent with production security settings
15
+ * const agent = createAgent({
16
+ * model,
17
+ * ...applySecurityPolicy("production"),
18
+ * });
19
+ *
20
+ * // Or customize a preset
21
+ * const customPolicy = applySecurityPolicy("ci", {
22
+ * sandbox: { timeout: 60000 },
23
+ * permissionMode: "plan",
24
+ * });
25
+ * ```
26
+ *
27
+ * @packageDocumentation
28
+ */
29
+ import type { LocalSandboxOptions } from "../backends/sandbox.js";
30
+ import { LocalSandbox } from "../backends/sandbox.js";
31
+ import type { HookRegistration, PermissionMode } from "../types.js";
32
+ /**
33
+ * File write patterns that should be blocked when acceptEdits mode is active.
34
+ * These patterns match common shell operations that perform file writes,
35
+ * which would bypass the file edit tool permission checks.
36
+ *
37
+ * @internal
38
+ */
39
+ export declare const ACCEPT_EDITS_BLOCKED_PATTERNS: RegExp[];
40
+ /**
41
+ * Security policy configuration that bundles sandbox, permission, and hook settings.
42
+ *
43
+ * This type combines multiple security controls into a single policy that can be
44
+ * applied to an agent. Policies can be created from presets or customized.
45
+ *
46
+ * @example
47
+ * ```typescript
48
+ * const policy: SecurityPolicy = {
49
+ * sandbox: { allowDangerous: false, timeout: 30000 },
50
+ * permissionMode: "default",
51
+ * disallowedTools: ["bash"],
52
+ * hooks: { PreToolUse: [auditHook] },
53
+ * };
54
+ * ```
55
+ *
56
+ * @category Security
57
+ */
58
+ export interface SecurityPolicy {
59
+ /**
60
+ * Sandbox configuration for command execution security.
61
+ */
62
+ sandbox?: LocalSandboxOptions;
63
+ /**
64
+ * Permission mode for tool execution control.
65
+ */
66
+ permissionMode?: PermissionMode;
67
+ /**
68
+ * Tools that are explicitly disallowed.
69
+ */
70
+ disallowedTools?: string[];
71
+ /**
72
+ * Tools that are explicitly allowed (all others blocked).
73
+ */
74
+ allowedTools?: string[];
75
+ /**
76
+ * Hook registrations for lifecycle events.
77
+ */
78
+ hooks?: HookRegistration;
79
+ /**
80
+ * When true and permissionMode is "acceptEdits", automatically configures the
81
+ * sandbox to block shell-based file operations (e.g., echo > file, rm, mv).
82
+ * This prevents bash commands from bypassing the acceptEdits permission checks.
83
+ *
84
+ * @defaultValue true
85
+ */
86
+ blockShellFileOps?: boolean;
87
+ }
88
+ /**
89
+ * Preset names for common security levels.
90
+ *
91
+ * - `development`: Permissive settings for rapid iteration
92
+ * - `ci`: Restrictive settings for CI/CD environments
93
+ * - `production`: Balanced settings for production deployments
94
+ * - `readonly`: Maximum restrictions - no writes, no commands
95
+ *
96
+ * @category Security
97
+ */
98
+ export type SecurityPolicyPreset = "development" | "ci" | "production" | "readonly";
99
+ /**
100
+ * Apply a security policy preset to agent options.
101
+ *
102
+ * This function returns a partial AgentOptions object that can be spread into
103
+ * createAgent(). It configures the sandbox, permission mode, tool restrictions,
104
+ * and hooks according to the selected preset.
105
+ *
106
+ * When permissionMode is "acceptEdits" and blockShellFileOps is true (default),
107
+ * the sandbox will be automatically configured to block shell-based file operations
108
+ * like `echo > file`, `rm`, `mv`, etc. This prevents bash commands from bypassing
109
+ * the acceptEdits permission checks.
110
+ *
111
+ * @param preset - The security preset to apply
112
+ * @param overrides - Optional policy overrides to customize the preset
113
+ * @returns Partial agent options with security settings applied
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * // Apply production preset
118
+ * const agent = createAgent({
119
+ * model,
120
+ * ...applySecurityPolicy("production"),
121
+ * });
122
+ *
123
+ * // Apply CI preset with custom timeout
124
+ * const ciAgent = createAgent({
125
+ * model,
126
+ * ...applySecurityPolicy("ci", {
127
+ * sandbox: { timeout: 120000 },
128
+ * }),
129
+ * });
130
+ *
131
+ * // Apply readonly preset for audit-only agent
132
+ * const auditAgent = createAgent({
133
+ * model,
134
+ * ...applySecurityPolicy("readonly"),
135
+ * });
136
+ *
137
+ * // Use acceptEdits mode with shell file operation blocking
138
+ * const editAgent = createAgent({
139
+ * model,
140
+ * ...applySecurityPolicy("development", {
141
+ * permissionMode: "acceptEdits",
142
+ * blockShellFileOps: true, // default, blocks bash file ops
143
+ * }),
144
+ * });
145
+ * ```
146
+ *
147
+ * @category Security
148
+ */
149
+ export declare function applySecurityPolicy(preset: SecurityPolicyPreset, overrides?: Partial<SecurityPolicy>): {
150
+ backend: LocalSandbox;
151
+ permissionMode?: PermissionMode;
152
+ allowedTools?: string[];
153
+ disallowedTools?: string[];
154
+ hooks?: HookRegistration;
155
+ };
156
+ /**
157
+ * Helper function to get sandbox options that block shell-based file operations.
158
+ * Use this when you want to enable "acceptEdits" permission mode while preventing
159
+ * bash commands from bypassing the file edit restrictions.
160
+ *
161
+ * @param baseOptions - Optional base sandbox options to extend
162
+ * @returns Sandbox options with file operation blocking enabled
163
+ *
164
+ * @example
165
+ * ```typescript
166
+ * import { LocalSandbox } from "@lleverage-ai/agent-sdk/backends";
167
+ * import { getSandboxOptionsForAcceptEdits } from "@lleverage-ai/agent-sdk/security";
168
+ *
169
+ * const agent = createAgent({
170
+ * model,
171
+ * backend: new LocalSandbox(getSandboxOptionsForAcceptEdits()),
172
+ * permissionMode: "acceptEdits",
173
+ * });
174
+ * ```
175
+ *
176
+ * @category Security
177
+ */
178
+ export declare function getSandboxOptionsForAcceptEdits(baseOptions?: LocalSandboxOptions): LocalSandboxOptions;
179
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAyBjD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAE9B;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAEzB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,IAAI,GAAG,YAAY,GAAG,UAAU,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAClC;IACD,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B,CAmCA;AA4JD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,CAAC,EAAE,mBAAmB,GAChC,mBAAmB,CAMrB"}
@@ -0,0 +1,323 @@
1
+ /**
2
+ * Security policy presets for agent configuration.
3
+ *
4
+ * This module provides security policy presets that bundle together sandbox configuration,
5
+ * permission modes, and hook settings to enforce different security levels. The presets help
6
+ * developers quickly configure agents for different environments (development, CI, production)
7
+ * without manually configuring each security control.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * import { createAgent } from "@lleverage-ai/agent-sdk";
12
+ * import { applySecurityPolicy, SecurityPolicyPreset } from "@lleverage-ai/agent-sdk/security";
13
+ *
14
+ * // Create an agent with production security settings
15
+ * const agent = createAgent({
16
+ * model,
17
+ * ...applySecurityPolicy("production"),
18
+ * });
19
+ *
20
+ * // Or customize a preset
21
+ * const customPolicy = applySecurityPolicy("ci", {
22
+ * sandbox: { timeout: 60000 },
23
+ * permissionMode: "plan",
24
+ * });
25
+ * ```
26
+ *
27
+ * @packageDocumentation
28
+ */
29
+ import { LocalSandbox } from "../backends/sandbox.js";
30
+ /**
31
+ * File write patterns that should be blocked when acceptEdits mode is active.
32
+ * These patterns match common shell operations that perform file writes,
33
+ * which would bypass the file edit tool permission checks.
34
+ *
35
+ * @internal
36
+ */
37
+ export const ACCEPT_EDITS_BLOCKED_PATTERNS = [
38
+ // Output redirection
39
+ />/,
40
+ // File deletion and movement
41
+ /\brm\b/i,
42
+ /\bmv\b/i,
43
+ // File creation and modification
44
+ /\btouch\b/i,
45
+ /\bcp\b/i,
46
+ // Directory operations
47
+ /\bmkdir\b/i,
48
+ /\brmdir\b/i,
49
+ // File permissions
50
+ /\bchmod\b/i,
51
+ /\bchown\b/i,
52
+ // Link creation
53
+ /\bln\b/i,
54
+ // Disk operations
55
+ /\bdd\b/i,
56
+ // Text editor invocations that might modify files
57
+ /\b(nano|vi|vim|emacs|sed -i)\b/i,
58
+ // Package managers that modify filesystem
59
+ /\bnpm\s+(install|uninstall|update)/i,
60
+ /\byarn\s+(add|remove)/i,
61
+ /\bpip\s+(install|uninstall)/i,
62
+ ];
63
+ /**
64
+ * Apply a security policy preset to agent options.
65
+ *
66
+ * This function returns a partial AgentOptions object that can be spread into
67
+ * createAgent(). It configures the sandbox, permission mode, tool restrictions,
68
+ * and hooks according to the selected preset.
69
+ *
70
+ * When permissionMode is "acceptEdits" and blockShellFileOps is true (default),
71
+ * the sandbox will be automatically configured to block shell-based file operations
72
+ * like `echo > file`, `rm`, `mv`, etc. This prevents bash commands from bypassing
73
+ * the acceptEdits permission checks.
74
+ *
75
+ * @param preset - The security preset to apply
76
+ * @param overrides - Optional policy overrides to customize the preset
77
+ * @returns Partial agent options with security settings applied
78
+ *
79
+ * @example
80
+ * ```typescript
81
+ * // Apply production preset
82
+ * const agent = createAgent({
83
+ * model,
84
+ * ...applySecurityPolicy("production"),
85
+ * });
86
+ *
87
+ * // Apply CI preset with custom timeout
88
+ * const ciAgent = createAgent({
89
+ * model,
90
+ * ...applySecurityPolicy("ci", {
91
+ * sandbox: { timeout: 120000 },
92
+ * }),
93
+ * });
94
+ *
95
+ * // Apply readonly preset for audit-only agent
96
+ * const auditAgent = createAgent({
97
+ * model,
98
+ * ...applySecurityPolicy("readonly"),
99
+ * });
100
+ *
101
+ * // Use acceptEdits mode with shell file operation blocking
102
+ * const editAgent = createAgent({
103
+ * model,
104
+ * ...applySecurityPolicy("development", {
105
+ * permissionMode: "acceptEdits",
106
+ * blockShellFileOps: true, // default, blocks bash file ops
107
+ * }),
108
+ * });
109
+ * ```
110
+ *
111
+ * @category Security
112
+ */
113
+ export function applySecurityPolicy(preset, overrides) {
114
+ // Get base policy for preset
115
+ const basePolicy = getPresetPolicy(preset);
116
+ // Merge with overrides
117
+ const policy = {
118
+ sandbox: { ...basePolicy.sandbox, ...overrides?.sandbox },
119
+ permissionMode: overrides?.permissionMode ?? basePolicy.permissionMode,
120
+ allowedTools: overrides?.allowedTools ?? basePolicy.allowedTools,
121
+ disallowedTools: overrides?.disallowedTools ?? basePolicy.disallowedTools,
122
+ hooks: overrides?.hooks ?? basePolicy.hooks,
123
+ blockShellFileOps: overrides?.blockShellFileOps ?? basePolicy.blockShellFileOps ?? true,
124
+ };
125
+ // If acceptEdits mode is enabled and blockShellFileOps is true,
126
+ // add shell file operation patterns to blocked commands
127
+ if (policy.permissionMode === "acceptEdits" && policy.blockShellFileOps) {
128
+ const existingBlocked = policy.sandbox?.blockedCommands ?? [];
129
+ policy.sandbox = {
130
+ ...policy.sandbox,
131
+ blockedCommands: [...existingBlocked, ...ACCEPT_EDITS_BLOCKED_PATTERNS],
132
+ };
133
+ }
134
+ // Create sandbox backend
135
+ const backend = new LocalSandbox(policy.sandbox);
136
+ // Return agent options
137
+ return {
138
+ backend,
139
+ permissionMode: policy.permissionMode,
140
+ allowedTools: policy.allowedTools,
141
+ disallowedTools: policy.disallowedTools,
142
+ hooks: policy.hooks,
143
+ };
144
+ }
145
+ /**
146
+ * Get the security policy configuration for a preset.
147
+ * @internal
148
+ */
149
+ function getPresetPolicy(preset) {
150
+ switch (preset) {
151
+ case "development":
152
+ return getDevelopmentPolicy();
153
+ case "ci":
154
+ return getCiPolicy();
155
+ case "production":
156
+ return getProductionPolicy();
157
+ case "readonly":
158
+ return getReadOnlyPolicy();
159
+ default:
160
+ throw new Error(`Unknown security preset: ${preset}`);
161
+ }
162
+ }
163
+ /**
164
+ * Development preset - permissive settings for rapid iteration.
165
+ *
166
+ * Features:
167
+ * - Allows all commands (including dangerous ones)
168
+ * - 2 minute timeout
169
+ * - No tool restrictions
170
+ * - Default permission mode (prompts for unclear cases)
171
+ *
172
+ * @internal
173
+ */
174
+ function getDevelopmentPolicy() {
175
+ return {
176
+ sandbox: {
177
+ allowDangerous: true,
178
+ timeout: 120000,
179
+ maxFileSizeMb: 100,
180
+ },
181
+ permissionMode: "default",
182
+ };
183
+ }
184
+ /**
185
+ * CI preset - restrictive settings for automated testing.
186
+ *
187
+ * Features:
188
+ * - Blocks dangerous commands (rm -rf, shutdown, etc.)
189
+ * - 5 minute timeout (for long test suites)
190
+ * - Blocks network-related operations
191
+ * - Plan mode (no tool execution, analysis only)
192
+ *
193
+ * @internal
194
+ */
195
+ function getCiPolicy() {
196
+ return {
197
+ sandbox: {
198
+ allowDangerous: false,
199
+ timeout: 300000, // 5 minutes
200
+ maxFileSizeMb: 50,
201
+ blockedCommands: [
202
+ // Network operations that might be unstable in CI
203
+ /curl/i,
204
+ /wget/i,
205
+ /git\s+push/i,
206
+ /npm\s+publish/i,
207
+ /docker\s+push/i,
208
+ ],
209
+ },
210
+ permissionMode: "plan", // No tool execution in CI
211
+ disallowedTools: [
212
+ "bash", // Block direct bash access
213
+ "execute", // Block generic execute
214
+ ],
215
+ };
216
+ }
217
+ /**
218
+ * Production preset - balanced settings for production deployments.
219
+ *
220
+ * Features:
221
+ * - Blocks dangerous commands
222
+ * - 1 minute timeout (fail fast)
223
+ * - Limited file operations (10MB max)
224
+ * - Default permission mode with tool restrictions
225
+ * - Blocks destructive operations
226
+ *
227
+ * @internal
228
+ */
229
+ function getProductionPolicy() {
230
+ return {
231
+ sandbox: {
232
+ allowDangerous: false,
233
+ timeout: 60000, // 1 minute
234
+ maxFileSizeMb: 10,
235
+ blockedCommands: [
236
+ // Block package management (immutable production)
237
+ /npm\s+(install|uninstall|update|publish)/i,
238
+ /yarn\s+(add|remove|upgrade|publish)/i,
239
+ /pip\s+(install|uninstall)/i,
240
+ // Block git writes
241
+ /git\s+(push|commit|merge|rebase)/i,
242
+ ],
243
+ },
244
+ permissionMode: "default",
245
+ disallowedTools: [
246
+ "write", // Block file writes
247
+ "edit", // Block file edits
248
+ ],
249
+ };
250
+ }
251
+ /**
252
+ * Read-only preset - maximum restrictions for audit-only agents.
253
+ *
254
+ * Features:
255
+ * - Blocks all write and modification commands
256
+ * - 30 second timeout
257
+ * - Very limited file operations (read-only, 5MB max)
258
+ * - Plan mode (no tool execution)
259
+ * - Blocks all write operations
260
+ *
261
+ * @internal
262
+ */
263
+ function getReadOnlyPolicy() {
264
+ return {
265
+ sandbox: {
266
+ allowDangerous: false,
267
+ timeout: 30000, // 30 seconds
268
+ maxFileSizeMb: 5,
269
+ // Use blockedCommands from LocalSandbox.readOnly() pattern
270
+ blockedCommands: [
271
+ /\brm\b/i,
272
+ /\bmv\b/i,
273
+ /\bcp\b/i,
274
+ /\btouch\b/i,
275
+ /\bmkdir\b/i,
276
+ /\brmdir\b/i,
277
+ /\bchmod\b/i,
278
+ /\bchown\b/i,
279
+ /\bln\b/i,
280
+ />/,
281
+ /\bdd\b/i,
282
+ /\bwrite\b/i,
283
+ /\bnpm\s+(install|uninstall|update|publish)/i,
284
+ /\byarn\s+(add|remove|upgrade|publish)/i,
285
+ /\bpip\s+(install|uninstall)/i,
286
+ /\bgit\s+(push|commit|merge|rebase)/i,
287
+ ],
288
+ },
289
+ permissionMode: "plan", // No tool execution
290
+ disallowedTools: ["bash", "execute", "write", "edit"],
291
+ allowedTools: ["read", "glob", "grep", "ls"],
292
+ };
293
+ }
294
+ /**
295
+ * Helper function to get sandbox options that block shell-based file operations.
296
+ * Use this when you want to enable "acceptEdits" permission mode while preventing
297
+ * bash commands from bypassing the file edit restrictions.
298
+ *
299
+ * @param baseOptions - Optional base sandbox options to extend
300
+ * @returns Sandbox options with file operation blocking enabled
301
+ *
302
+ * @example
303
+ * ```typescript
304
+ * import { LocalSandbox } from "@lleverage-ai/agent-sdk/backends";
305
+ * import { getSandboxOptionsForAcceptEdits } from "@lleverage-ai/agent-sdk/security";
306
+ *
307
+ * const agent = createAgent({
308
+ * model,
309
+ * backend: new LocalSandbox(getSandboxOptionsForAcceptEdits()),
310
+ * permissionMode: "acceptEdits",
311
+ * });
312
+ * ```
313
+ *
314
+ * @category Security
315
+ */
316
+ export function getSandboxOptionsForAcceptEdits(baseOptions) {
317
+ const existingBlocked = baseOptions?.blockedCommands ?? [];
318
+ return {
319
+ ...baseOptions,
320
+ blockedCommands: [...existingBlocked, ...ACCEPT_EDITS_BLOCKED_PATTERNS],
321
+ };
322
+ }
323
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"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"}