@guren/server 2.15.0 → 2.17.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 (302) hide show
  1. package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
  2. package/dist/{Hash-C8aejmi8.js → Hash-D2DFd8xX.js} +7 -57
  3. package/dist/{HttpException-BkS3euNG.js → HttpException-BlQ2yEmT.js} +2 -79
  4. package/dist/{Job-BVT813DO.js → Job-DxQK8h3P.js} +24 -179
  5. package/dist/{McpServiceProvider-BawsYjgN.js → McpServiceProvider-Zihx3Bjq.js} +35 -20
  6. package/dist/{Random-DbIJ22KQ.js → Random-S0OvCuR8.js} +9 -106
  7. package/dist/agent/AgentApprovalRequested.d.ts +11 -39
  8. package/dist/agent/approval-status.d.ts +56 -0
  9. package/dist/agent/approval.d.ts +76 -187
  10. package/dist/agent/audit-emitter.d.ts +16 -44
  11. package/dist/agent/audit.d.ts +20 -56
  12. package/dist/agent/derive.d.ts +32 -66
  13. package/dist/agent/dispatch.d.ts +38 -90
  14. package/dist/agent/events.d.ts +17 -23
  15. package/dist/agent/gate.d.ts +118 -0
  16. package/dist/agent/meta-tools.d.ts +18 -46
  17. package/dist/agent/pipeline.d.ts +234 -0
  18. package/dist/agent/public.d.ts +6 -25
  19. package/dist/agent/public.js +1 -1
  20. package/dist/agent/redact.d.ts +16 -38
  21. package/dist/agent/scopes.d.ts +55 -69
  22. package/dist/auth/AgentPrincipalGuard.d.ts +49 -0
  23. package/dist/auth/AuthManager.d.ts +22 -43
  24. package/dist/auth/AuthenticatableModel.d.ts +2 -2
  25. package/dist/auth/SessionGuard.d.ts +0 -1
  26. package/dist/auth/TokenGuard.d.ts +6 -26
  27. package/dist/auth/api-token.d.ts +16 -148
  28. package/dist/auth/context.d.ts +5 -10
  29. package/dist/auth/email-verification.d.ts +29 -127
  30. package/dist/auth/index.js +1 -1
  31. package/dist/auth/oauth/index.d.ts +35 -57
  32. package/dist/auth/password/DefaultHasher.d.ts +5 -14
  33. package/dist/auth/password/PasswordHasher.d.ts +5 -13
  34. package/dist/auth/password/hash-format.d.ts +5 -13
  35. package/dist/auth/password-reset.d.ts +16 -42
  36. package/dist/auth/providers/ModelUserProvider.d.ts +3 -4
  37. package/dist/auth/providers/UserProvider.d.ts +4 -4
  38. package/dist/auth/signed-token.d.ts +18 -0
  39. package/dist/auth/types.d.ts +9 -32
  40. package/dist/auth/utils.d.ts +6 -27
  41. package/dist/{auth-DkYoAPVn.js → auth-Gg54ppQi.js} +279 -519
  42. package/dist/authorization/Gate.d.ts +9 -145
  43. package/dist/authorization/Policy.d.ts +6 -53
  44. package/dist/authorization/index.js +1 -1
  45. package/dist/authorization/middleware.d.ts +16 -62
  46. package/dist/authorization/types.d.ts +8 -64
  47. package/dist/{authorization-CdfbCj8J.js → authorization-CdEWZZw3.js} +44 -309
  48. package/dist/broadcasting/BroadcastManager.d.ts +29 -149
  49. package/dist/broadcasting/channels/Channel.d.ts +1 -19
  50. package/dist/broadcasting/channels/PresenceChannel.d.ts +1 -55
  51. package/dist/broadcasting/channels/PrivateChannel.d.ts +1 -23
  52. package/dist/broadcasting/drivers/MemoryDriver.d.ts +18 -70
  53. package/dist/broadcasting/drivers/RedisDriver.d.ts +3 -80
  54. package/dist/broadcasting/drivers/index.d.ts +1 -1
  55. package/dist/broadcasting/index.d.ts +1 -1
  56. package/dist/broadcasting/index.js +1 -1
  57. package/dist/broadcasting/types.d.ts +7 -88
  58. package/dist/{broadcasting-BwodCA4q.js → broadcasting-B5RzB0A2.js} +87 -414
  59. package/dist/cache/CacheManager.d.ts +8 -62
  60. package/dist/cache/TaggedCache.d.ts +2 -35
  61. package/dist/cache/index.js +1 -1
  62. package/dist/cache/stores/FileStore.d.ts +2 -36
  63. package/dist/cache/stores/MemoryStore.d.ts +2 -26
  64. package/dist/cache/stores/RedisStore.d.ts +1 -29
  65. package/dist/cache/types.d.ts +21 -128
  66. package/dist/{cache-BYnZf2FR.js → cache-BOOIr324.js} +19 -198
  67. package/dist/client-C4TEr_Dd.js +9 -0
  68. package/dist/console/Command.d.ts +17 -126
  69. package/dist/console/ConsoleKernel.d.ts +2 -74
  70. package/dist/console/Input.d.ts +5 -113
  71. package/dist/console/Output.d.ts +3 -99
  72. package/dist/console/types.d.ts +3 -33
  73. package/dist/container/Container.d.ts +12 -103
  74. package/dist/container/ServiceProvider.d.ts +17 -61
  75. package/dist/container/bindings.d.ts +5 -26
  76. package/dist/container/defineModule.d.ts +16 -54
  77. package/dist/container/definePlugin.d.ts +12 -45
  78. package/dist/container/types.d.ts +2 -34
  79. package/dist/context-CXk_umpT.js +21 -0
  80. package/dist/database/Factory.d.ts +4 -57
  81. package/dist/database/Seeder.d.ts +8 -46
  82. package/dist/database/SeederRunner.d.ts +3 -33
  83. package/dist/database/types.d.ts +3 -24
  84. package/dist/discovery/AutoDiscovery.d.ts +10 -82
  85. package/dist/{dispatch-erOS9epZ.js → dispatch-BAwzftws.js} +32 -79
  86. package/dist/docs-viewer/DocsViewerServiceProvider.d.ts +2 -5
  87. package/dist/docs-viewer/endpoint.d.ts +5 -11
  88. package/dist/encryption/Encrypter.d.ts +5 -71
  89. package/dist/encryption/Hash.d.ts +7 -57
  90. package/dist/encryption/Random.d.ts +6 -99
  91. package/dist/encryption/index.js +3 -3
  92. package/dist/encryption/types.d.ts +10 -72
  93. package/dist/{encryption-D99Vmls3.js → encryption-uwP3Di4D.js} +9 -78
  94. package/dist/{endpoint-D6GIqOpe.js → endpoint-BXipU2Jj.js} +6 -12
  95. package/dist/endpoint-Dsw3Acvq.js +26 -0
  96. package/dist/errors/ExceptionHandler.d.ts +3 -90
  97. package/dist/errors/HttpException.d.ts +2 -79
  98. package/dist/errors/debug-page.d.ts +3 -17
  99. package/dist/errors/error-page.d.ts +1 -0
  100. package/dist/errors/exceptions/AuthenticationException.d.ts +2 -24
  101. package/dist/errors/exceptions/AuthorizationException.d.ts +1 -24
  102. package/dist/errors/exceptions/MethodNotAllowedException.d.ts +1 -23
  103. package/dist/errors/exceptions/NotFoundHttpException.d.ts +1 -27
  104. package/dist/errors/exceptions/ValidationException.d.ts +2 -43
  105. package/dist/errors/types.d.ts +1 -25
  106. package/dist/{errors-BgeOl_DC.js → errors-JpkcCjjn.js} +3 -41
  107. package/dist/events/Event.d.ts +1 -28
  108. package/dist/events/EventManager.d.ts +5 -107
  109. package/dist/events/Listener.d.ts +7 -55
  110. package/dist/events/builtin.d.ts +0 -24
  111. package/dist/events/index.js +1 -1
  112. package/dist/events/types.d.ts +4 -22
  113. package/dist/{events-aIH_bWRx.js → events-DOmAHDeP.js} +11 -191
  114. package/dist/facades/index.d.ts +2 -14
  115. package/dist/health/HealthCheck.d.ts +0 -24
  116. package/dist/health/HealthManager.d.ts +0 -36
  117. package/dist/health/checks/CacheCheck.d.ts +2 -17
  118. package/dist/health/checks/CustomCheck.d.ts +0 -9
  119. package/dist/health/checks/DatabaseCheck.d.ts +2 -17
  120. package/dist/health/checks/MemoryCheck.d.ts +3 -12
  121. package/dist/health/checks/RedisCheck.d.ts +1 -13
  122. package/dist/health/checks/StorageCheck.d.ts +2 -17
  123. package/dist/health/index.js +1 -1
  124. package/dist/health/types.d.ts +4 -24
  125. package/dist/{health-VWdWXRwh.js → health-DQSvUplL.js} +1 -76
  126. package/dist/hot-disposables-B5BXqaIH.js +167 -0
  127. package/dist/hot-reload/hot-disposables.d.ts +22 -74
  128. package/dist/hot-reload/testing.d.ts +4 -9
  129. package/dist/http/Application.d.ts +77 -205
  130. package/dist/http/FormRequest.d.ts +4 -55
  131. package/dist/http/dev-assets.d.ts +13 -31
  132. package/dist/http/dev-banner.d.ts +2 -5
  133. package/dist/http/inertia-assets.d.ts +3 -6
  134. package/dist/http/middleware/capabilities.d.ts +27 -50
  135. package/dist/http/middleware/cors.d.ts +4 -29
  136. package/dist/http/middleware/csp.d.ts +2 -25
  137. package/dist/http/middleware/csrf.d.ts +28 -95
  138. package/dist/http/middleware/detect-locale.d.ts +7 -27
  139. package/dist/http/middleware/force-https.d.ts +6 -24
  140. package/dist/http/middleware/host-authorization.d.ts +2 -12
  141. package/dist/http/middleware/index.d.ts +1 -1
  142. package/dist/http/middleware/loopback-guard.d.ts +15 -33
  143. package/dist/http/middleware/rate-limit.d.ts +29 -126
  144. package/dist/http/middleware/redirect-safety.d.ts +2 -20
  145. package/dist/http/middleware/request-id.d.ts +1 -14
  146. package/dist/http/middleware/request-logging.d.ts +2 -13
  147. package/dist/http/middleware/response-headers.d.ts +5 -13
  148. package/dist/http/middleware/security-headers.d.ts +2 -16
  149. package/dist/http/middleware/session.d.ts +15 -34
  150. package/dist/http/middleware/validation-errors-cookie.d.ts +7 -18
  151. package/dist/http/middleware/validation.d.ts +8 -63
  152. package/dist/http/public-assets.d.ts +11 -7
  153. package/dist/http/request.d.ts +32 -118
  154. package/dist/http/resources/CursorPaginator.d.ts +5 -64
  155. package/dist/http/resources/Paginator.d.ts +7 -84
  156. package/dist/http/resources/Resource.d.ts +9 -65
  157. package/dist/http/resources/ResourceCollection.d.ts +5 -39
  158. package/dist/http/resources/types.d.ts +10 -30
  159. package/dist/http/static-documents.d.ts +10 -20
  160. package/dist/http/validation/Validator.d.ts +25 -85
  161. package/dist/http/validation/rules.d.ts +48 -147
  162. package/dist/http/validation/types.d.ts +16 -61
  163. package/dist/http/vite-assets.d.ts +5 -28
  164. package/dist/http/vite-dev-server.d.ts +6 -9
  165. package/dist/http/vite-manifest.d.ts +19 -33
  166. package/dist/i18n/I18nManager.d.ts +12 -78
  167. package/dist/i18n/Translator.d.ts +3 -54
  168. package/dist/i18n/index.js +1 -1
  169. package/dist/i18n/loaders/JsonLoader.d.ts +4 -31
  170. package/dist/i18n/loaders/MemoryLoader.d.ts +1 -21
  171. package/dist/i18n/pluralization.d.ts +4 -13
  172. package/dist/i18n/types.d.ts +17 -69
  173. package/dist/{i18n-mcWi7LCd.js → i18n-Cg1aajRP.js} +31 -225
  174. package/dist/index.d.ts +11 -4
  175. package/dist/index.js +1186 -3040
  176. package/dist/internal/agent-preflight.d.ts +9 -21
  177. package/dist/internal/agent-principal.d.ts +32 -0
  178. package/dist/internal/request.d.ts +6 -19
  179. package/dist/internal/request.js +1 -1
  180. package/dist/internal/route-path.d.ts +9 -21
  181. package/dist/internal/route-path.js +9 -21
  182. package/dist/internal/zod-compat.d.ts +55 -122
  183. package/dist/internal/zod-compat.js +39 -70
  184. package/dist/internal/zod-json-schema.d.ts +18 -54
  185. package/dist/internal/zod-json-schema.js +46 -123
  186. package/dist/jsx-runtime.d.ts +3 -8
  187. package/dist/lambda/index.d.ts +17 -79
  188. package/dist/lambda/index.js +11 -59
  189. package/dist/logging/LogManager.d.ts +1 -51
  190. package/dist/logging/Logger.d.ts +8 -47
  191. package/dist/logging/channels/ConsoleChannel.d.ts +1 -3
  192. package/dist/logging/channels/DailyFileChannel.d.ts +1 -3
  193. package/dist/logging/channels/FileChannel.d.ts +1 -3
  194. package/dist/logging/daily-file-path.d.ts +7 -16
  195. package/dist/logging/index.js +1 -1
  196. package/dist/logging/types.d.ts +13 -45
  197. package/dist/{logging-B-kngi3q.js → logging-zOY1XCtq.js} +52 -141
  198. package/dist/{loopback-guard-D0Kc7-xc.js → loopback-guard-DT9gHF0F.js} +41 -92
  199. package/dist/mail/Mail.d.ts +10 -106
  200. package/dist/mail/MailManager.d.ts +2 -60
  201. package/dist/mail/index.js +1 -1
  202. package/dist/mail/transports/LogTransport.d.ts +1 -4
  203. package/dist/mail/transports/MemoryTransport.d.ts +1 -63
  204. package/dist/mail/transports/ResendTransport.d.ts +1 -23
  205. package/dist/mail/transports/SmtpTransport.d.ts +1 -31
  206. package/dist/mail/types.d.ts +28 -150
  207. package/dist/{mail-DfEfSQEr.js → mail-76DWy9lj.js} +31 -289
  208. package/dist/mcp/McpServiceProvider.d.ts +4 -10
  209. package/dist/mcp/create-mcp-server.d.ts +42 -57
  210. package/dist/mcp/endpoint.d.ts +12 -36
  211. package/dist/mcp/index.js +1 -1
  212. package/dist/mvc/Controller.d.ts +46 -227
  213. package/dist/mvc/Router.d.ts +50 -129
  214. package/dist/mvc/inertia/InertiaEngine.d.ts +18 -48
  215. package/dist/mvc/inertia/shared.d.ts +6 -19
  216. package/dist/mvc/mount-route.d.ts +2 -6
  217. package/dist/mvc/view.d.ts +1 -2
  218. package/dist/notifications/Notification.d.ts +8 -75
  219. package/dist/notifications/NotificationManager.d.ts +15 -88
  220. package/dist/notifications/channels/DatabaseChannel.d.ts +1 -41
  221. package/dist/notifications/channels/MailChannel.d.ts +2 -31
  222. package/dist/notifications/channels/MemoryChannel.d.ts +2 -62
  223. package/dist/notifications/channels/SlackChannel.d.ts +3 -48
  224. package/dist/notifications/index.js +1 -1
  225. package/dist/notifications/notifiable-type.d.ts +3 -6
  226. package/dist/notifications/registry.d.ts +8 -27
  227. package/dist/notifications/types.d.ts +16 -53
  228. package/dist/{notifications-BGqmUNZ8.js → notifications-okWFs9ly.js} +37 -335
  229. package/dist/providers/AuthServiceProvider.d.ts +1 -3
  230. package/dist/providers/AuthorizationServiceProvider.d.ts +2 -3
  231. package/dist/providers/BroadcastServiceProvider.d.ts +1 -3
  232. package/dist/providers/CacheServiceProvider.d.ts +1 -3
  233. package/dist/providers/EncryptionServiceProvider.d.ts +1 -3
  234. package/dist/providers/ErrorServiceProvider.d.ts +1 -4
  235. package/dist/providers/EventServiceProvider.d.ts +1 -3
  236. package/dist/providers/HealthServiceProvider.d.ts +1 -3
  237. package/dist/providers/I18nServiceProvider.d.ts +6 -10
  238. package/dist/providers/InertiaServiceProvider.d.ts +1 -4
  239. package/dist/providers/LogServiceProvider.d.ts +1 -3
  240. package/dist/providers/MailServiceProvider.d.ts +1 -3
  241. package/dist/providers/NotificationServiceProvider.d.ts +1 -3
  242. package/dist/providers/OAuthServiceProvider.d.ts +1 -3
  243. package/dist/providers/QueueServiceProvider.d.ts +1 -3
  244. package/dist/providers/SchedulingServiceProvider.d.ts +1 -3
  245. package/dist/providers/StorageServiceProvider.d.ts +1 -3
  246. package/dist/queue/FailedJobReporter.d.ts +1 -24
  247. package/dist/queue/Job.d.ts +12 -99
  248. package/dist/queue/QueueManager.d.ts +6 -57
  249. package/dist/queue/Worker.d.ts +4 -65
  250. package/dist/queue/drivers/MemoryDriver.d.ts +3 -44
  251. package/dist/queue/drivers/RedisDriver.d.ts +7 -65
  252. package/dist/queue/drivers/SqsDriver.d.ts +6 -57
  253. package/dist/queue/drivers/SyncDriver.d.ts +10 -13
  254. package/dist/queue/index.js +2 -2
  255. package/dist/queue/types.d.ts +10 -92
  256. package/dist/{queue-CXrRK85G.js → queue-CcXCjuJI.js} +32 -260
  257. package/dist/redis/RedisApiTokenStore.d.ts +4 -56
  258. package/dist/redis/RedisEmailVerificationStore.d.ts +4 -37
  259. package/dist/redis/RedisOAuthStateStore.d.ts +2 -10
  260. package/dist/redis/RedisPasswordResetStore.d.ts +4 -37
  261. package/dist/redis/RedisRateLimitStore.d.ts +16 -49
  262. package/dist/redis/RedisSessionStore.d.ts +3 -44
  263. package/dist/redis/client.d.ts +2 -32
  264. package/dist/redis/index.js +47 -232
  265. package/dist/redis/redis-values.d.ts +6 -12
  266. package/dist/redis/scan-keys.d.ts +1 -4
  267. package/dist/request-CLOYytGP.js +68 -0
  268. package/dist/runtime/index.d.ts +2 -0
  269. package/dist/runtime/index.js +50 -92
  270. package/dist/scheduling/CronParser.d.ts +0 -29
  271. package/dist/scheduling/Schedule.d.ts +1 -153
  272. package/dist/scheduling/ScheduledTask.d.ts +0 -31
  273. package/dist/scheduling/Scheduler.d.ts +0 -70
  274. package/dist/scheduling/index.js +1 -1
  275. package/dist/scheduling/types.d.ts +4 -65
  276. package/dist/{scheduling-CPiEdtQd.js → scheduling-C6tcOtUl.js} +2 -287
  277. package/dist/storage/StorageManager.d.ts +0 -48
  278. package/dist/storage/drivers/LocalDriver.d.ts +1 -25
  279. package/dist/storage/drivers/MemoryDriver.d.ts +5 -35
  280. package/dist/storage/drivers/S3Driver.d.ts +6 -36
  281. package/dist/storage/drivers/s3-acl.d.ts +5 -10
  282. package/dist/storage/index.js +1 -1
  283. package/dist/storage/types.d.ts +27 -265
  284. package/dist/{storage-TLD9t0Q2.js → storage-BB59f07j.js} +17 -157
  285. package/dist/support/contained-path.d.ts +10 -20
  286. package/dist/support/error-polyfill.d.ts +4 -6
  287. package/dist/support/expiry.d.ts +17 -33
  288. package/dist/support/expiry.js +17 -33
  289. package/dist/support/import-map.d.ts +3 -7
  290. package/dist/support/inertia-defaults.d.ts +5 -10
  291. package/dist/support/redirect-target.d.ts +4 -6
  292. package/dist/support/stack-frames.d.ts +11 -50
  293. package/dist/support/trim-slashes.d.ts +4 -7
  294. package/dist/support/warn-once.d.ts +2 -6
  295. package/dist/{trim-slashes-ZJ_VsY5s.js → trim-slashes-BLY9hKAa.js} +4 -7
  296. package/dist/{vite-manifest-w_RSOvQW.js → vite-manifest-B_Iy5183.js} +34 -58
  297. package/package.json +2 -2
  298. package/dist/client-Dd7vLcqp.js +0 -27
  299. package/dist/context-DoD0c7J_.js +0 -26
  300. package/dist/endpoint-D-20PiHY.js +0 -46
  301. package/dist/hot-disposables-WsTX2ySN.js +0 -281
  302. package/dist/request-CVQwpu2J.js +0 -129
@@ -1,62 +1,32 @@
1
1
  /**
2
2
  * The agent approval queue (RFC 0016 §5.4 item 4): a tool declaring
3
- * `approval: 'required'` does not execute on request. The call becomes a
4
- * pending record, approvers are notified, and only a *human* decision turns
5
- * that record into permission for one later call.
6
- *
7
- * Declarations and pure derivation only, exactly as {@link file://./audit.ts}
8
- * beside it. Nothing here opens a database, reads a clock, or sends a
9
- * notification — every function that needs the instant takes it as an
10
- * argument, because this module is reachable from every runtime the framework
11
- * targets and because a rule that timestamped itself could not be pinned by a
12
- * test. *Where* records live is the application's decision, made once through
13
- * {@link AgentApprovalStore}; this module only says what one looks like and
14
- * what makes one usable.
15
- *
16
- * **Redaction is the emitter's contract, and nothing here may re-run it.**
17
- * {@link AgentApprovalRequest.input} arrives having already been through
18
- * `redactAgentArguments`, the same contract `events.ts` and `audit.ts` state:
19
- * a record is shown to a human approver and is persisted, so it carries the
20
- * masked copy. Masking again here would install a second, quieter redaction
21
- * rule beside the real one, and nothing reading a record could tell which of
22
- * them produced a mask it is looking at.
23
- *
24
- * That contract is exactly why the *fingerprint* is computed from the **raw**
25
- * arguments instead (see {@link agentApprovalFingerprint}). Binding an
26
- * approval to the redacted copy would make approving
27
- * `users.setPassword {id: 5, password: '…'}` authorize the same call with a
28
- * different password, since the two redact to the same object — the hole the
29
- * argument-binding rule exists to close.
3
+ * `approval: 'required'` becomes a pending record, approvers are notified, and
4
+ * only a *human* decision turns it into permission for one later call.
5
+ * Declarations and pure derivation only, like `audit.ts`: no database, clock or
6
+ * notification. {@link AgentApprovalRequest.input} arrives already redacted;
7
+ * the *fingerprint* is computed from the **raw** arguments, or approving
8
+ * `users.setPassword {id: 5, password: '…'}` would authorize the same call
9
+ * with a different password.
30
10
  */
31
11
  import type { AgentPrincipal } from './events.js';
32
12
  /**
33
- * How long a pending request stays answerable by default: one hour.
34
- *
35
- * An approval is permission for one call *now*, not a standing grant. The
36
- * default is short for the reason the single-use rule exists — an approval
37
- * granted last month must not let a call through today — and an application
38
- * that wants longer says so.
13
+ * How long a pending request stays answerable by default: one hour. An approval
14
+ * is permission for one call *now*, not a standing grant.
39
15
  */
40
16
  export declare const DEFAULT_AGENT_APPROVAL_TTL_MS: number;
41
17
  /**
42
- * The configuration key an adapter reads the queue out of, as a value.
43
- *
44
- * `guren check` fails a route declaring `approval: 'required'` in an app whose
45
- * `mcpPlugin({ … })` call carries no queue, and it finds that call by looking
46
- * for this key. The CLI cannot import `@guren/plugin-mcp` — it does not depend
47
- * on it, and an app that never installs App MCP is still checked — so without
48
- * this constant the check would restate the string and the two would drift:
49
- * renaming the option would leave the check passing every app, silently. Same
50
- * rule, two readers, as {@link file://./meta-tools.ts}.
18
+ * The configuration key an adapter reads the queue out of, as a value: `guren
19
+ * check` finds the `mcpPlugin({ … })` call by it and cannot import
20
+ * `@guren/plugin-mcp`, so a restated string would let a rename leave the check
21
+ * passing every app silently. Same rule, two readers, as
22
+ * {@link file://./meta-tools.ts}.
51
23
  */
52
24
  export declare const AGENT_APPROVAL_CONFIG_KEY = "approvals";
53
25
  /**
54
- * What a request is waiting for, or what happened to it.
55
- *
56
- * `'expired'` is a *stored* status only for a store that sweeps; the framework
57
- * never depends on one having done so — {@link agentApprovalStatusAt} derives
58
- * expiry from `expiresAt` against a clock, so a store that never sweeps and one
59
- * that sweeps hourly answer the same question the same way.
26
+ * What a request is waiting for, or what happened to it. `'expired'` is a
27
+ * *stored* status only for a store that sweeps; {@link agentApprovalStatusAt}
28
+ * derives expiry from `expiresAt` against a clock, so a store that never
29
+ * sweeps and one that sweeps hourly answer the same way.
60
30
  */
61
31
  export type AgentApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
62
32
  /** One pending, answered, or spent approval request. */
@@ -71,11 +41,9 @@ export interface AgentApprovalRequest {
71
41
  */
72
42
  input: Record<string, unknown>;
73
43
  /**
74
- * {@link agentApprovalFingerprint} of the *raw* arguments. The record
75
- * carries the hash and never the canonical string: an approval store holding
76
- * a reversible copy of every argument an agent ever passed would be a second
77
- * place secrets live, and the redaction above exists precisely so the first
78
- * one does not.
44
+ * {@link agentApprovalFingerprint} of the *raw* arguments — the hash, never
45
+ * the canonical string: a store holding a reversible copy of every argument
46
+ * an agent ever passed would be a second place secrets live.
79
47
  */
80
48
  fingerprint: string;
81
49
  /** Who asked. `null` for a surface with no verified principal. */
@@ -93,10 +61,9 @@ export interface AgentApprovalRequest {
93
61
  /** ISO 8601, UTC — when a human answered. Absent while pending. */
94
62
  resolvedAt?: string;
95
63
  /**
96
- * Who answered, in whatever vocabulary the application approves in (a user
97
- * id, an email, a console operator's name). The framework never interprets
98
- * it; it exists so the audit answer to "who let this through" is in the
99
- * record rather than only in the approval UI's own logs.
64
+ * Who answered, in whatever vocabulary the application approves in. Never
65
+ * interpreted by the framework; it exists so the answer to "who let this
66
+ * through" is in the record rather than only in the approval UI's logs.
100
67
  */
101
68
  resolvedBy?: string;
102
69
  /** ISO 8601, UTC — when the approval was spent. Set by `consume`. */
@@ -110,116 +77,59 @@ export interface AgentApprovalMatch {
110
77
  }
111
78
  /**
112
79
  * Where pending approvals live. The application implements it; the framework
113
- * ships no default, for the reason the audit sink ships none: the runtimes
114
- * this endpoint serves include Workers and Lambda, and a queue that silently
115
- * degraded to process memory there would answer "approved" for a record the
116
- * next isolate has never heard of. An unconfigured queue refuses visibly
117
- * instead (`gateToolCall`'s fail-closed refusal names the configuration line).
118
- *
119
- * Four methods, each one the gate actually reaches for. Deliberately no
120
- * `list`, `approve`, or `reject`: resolving a request is a human action taken
121
- * through the application's own interface, over the application's own storage,
122
- * and a framework interface for it would be a second way to write records that
123
- * nothing here reads.
80
+ * ships no default, because a queue degrading to process memory on Workers or
81
+ * Lambda would answer "approved" for a record the next isolate never heard of
82
+ * (`gateToolCall` fails closed instead). No `list`/`approve`/`reject`: resolving
83
+ * a request is a human action, through the application's own interface.
124
84
  */
125
85
  export interface AgentApprovalStore {
126
86
  /** Persist a new pending request. */
127
87
  create(request: AgentApprovalRequest): Promise<void>;
128
88
  /**
129
- * The request with this id, or `null`. Backs `guren.approval_status`.
130
- *
131
- * Takes no principal: the caller-scoping rule is applied by the framework
132
- * (see {@link agentApprovalVisibleTo}), not by the store, because a store
133
- * that forgot to filter would leak other principals' pending actions and
134
- * nothing would fail.
89
+ * The request with this id, or `null`. Backs `guren.approval_status`. Takes
90
+ * no principal: the caller-scoping rule is applied by the framework (see
91
+ * {@link agentApprovalVisibleTo}), because a store that forgot to filter
92
+ * would leak other principals' pending actions and nothing would fail.
135
93
  */
136
94
  find(id: string): Promise<AgentApprovalRequest | null>;
137
95
  /**
138
- * The **unconsumed** record matching this exact call, or `null`. When more
139
- * than one matches, the most recently requested.
140
- *
141
- * Deliberately not "the approved one": the gate needs to see a *pending*
142
- * match too, or an agent that polls by re-calling the tool creates an
143
- * unbounded number of records and notifies approvers once per poll. It needs
144
- * to see a *rejected* one for the same reason. Expiry is not filtered here
145
- * either — see {@link agentApprovalUsableAt}.
96
+ * The **unconsumed** record matching this exact call, or `null`; the most
97
+ * recently requested when several match. Not "the approved one": the gate
98
+ * must see a *pending* or *rejected* match too, or an agent polling by
99
+ * re-calling the tool creates unbounded records and notifies approvers once
100
+ * per poll. Expiry is not filtered here either — see {@link agentApprovalUsableAt}.
146
101
  */
147
102
  findMatch(match: AgentApprovalMatch): Promise<AgentApprovalRequest | null>;
148
103
  /**
149
104
  * Spend the approval with this id, returning whether *this* call won it.
150
- *
151
- * Must be a compare-and-set: set `consumedAt` only if it is not already set,
152
- * and answer `false` when it was. Two concurrent calls will find the same
153
- * approved record — an approval is permission for one call, and a `consume`
154
- * implemented as an unconditional write hands it to both. The gate treats
155
- * `false` as "no approval", not as an error, and falls through to creating a
156
- * new pending record.
105
+ * Must be a compare-and-set: two concurrent calls find the same approved
106
+ * record, and an unconditional write hands it to both. The gate treats
107
+ * `false` as "no approval", not an error, and creates a new pending record.
157
108
  */
158
109
  consume(id: string): Promise<boolean>;
159
110
  }
160
111
  /**
161
- * A stable key for "the same caller".
162
- *
163
- * Kind and id only: a token's *abilities* are not part of the identity,
164
- * because a token rotated or re-scoped between the approval and the call is
165
- * still the same principal, and an approval a human granted should not
166
- * evaporate because an unrelated ability was added. The scope gate has already
167
- * run by the time this key is used, so the call's own authority is checked
168
- * regardless.
169
- *
170
- * The id's type is part of the key. `id: 5` and `id: '5'` are different
171
- * principals to every store that distinguishes them, and collapsing the two
172
- * here would let a service token named `"5"` spend a user 5 approval.
112
+ * A stable key for "the same caller". Kind and id only: a token's *abilities*
113
+ * are not part of the identity, so an approval a human granted survives a
114
+ * rotation or re-scope, and the scope gate has already run by the time this key
115
+ * is used. The id's type is part of the key — collapsing `5` and `'5'` would
116
+ * let a service token named `"5"` spend a user 5 approval.
173
117
  */
174
118
  export declare function agentApprovalPrincipalKey(principal: AgentPrincipal | null): string;
175
119
  /**
176
- * The canonical text of one call's arguments — the *only* rule for deciding
177
- * that two calls are the same call.
178
- *
179
- * One function, two readers: {@link agentApprovalFingerprint} hashes it when a
180
- * record is created and again when a call looks one up. A second
181
- * serialization is how approving `posts.destroy {id: 5}` comes to authorize
182
- * `{id: 9}` — the failure this whole binding exists to prevent — and it would
183
- * do it silently, because both sides would still produce *a* string.
184
- *
185
- * What it normalizes: object key order, at every depth. `{a: 1, b: 2}` and
186
- * `{b: 2, a: 1}` are the same call, nested or not.
187
- *
188
- * What it deliberately does **not** normalize, because each would make two
189
- * genuinely different calls match:
190
- *
191
- * - **Types.** `{id: 5}` and `{id: '5'}` are different calls. A route that
192
- * coerces them to the same value is coercing *after* the gate; the approver
193
- * saw one of the two written down.
194
- * - **Array order.** Order is meaning in a JSON array (`ids: [1, 2]` vs
195
- * `[2, 1]` may be the same call to one route and not to another) and the
196
- * framework cannot know which.
197
- * - **Absent vs. explicitly null.** A dropped key and `null` are different
198
- * inputs to a schema with a default.
199
- * - Unicode form, number spelling beyond what JSON already fixes, or
200
- * whitespace inside strings.
201
- *
202
- * Total over JSON, and deliberately *not* total over everything else: a value
203
- * JSON cannot carry throws rather than serializing to a placeholder. A
204
- * placeholder would make two distinct inputs canonicalize identically, which
205
- * is the one failure mode worse than refusing — and refusing is safe here,
206
- * because the gate turns a throw into a fail-closed refusal. Arguments reach
207
- * this function parsed from JSON-RPC, so no such value can occur in practice;
208
- * the rule is written down for the surface that one day passes one.
120
+ * The canonical text of one call's arguments — the *only* rule for "same
121
+ * call"; a second serialization is how approving `posts.destroy {id: 5}`
122
+ * silently comes to authorize `{id: 9}`. Normalizes object key order at every
123
+ * depth, nothing else: types, array order and absent-vs-null distinguish calls.
124
+ * A value JSON cannot carry throws; the gate turns that into a fail-closed refusal.
209
125
  */
210
126
  export declare function canonicalizeAgentApprovalInput(input: Record<string, unknown>): string;
211
127
  /**
212
128
  * The fingerprint an approval is bound to: SHA-256 of
213
- * {@link canonicalizeAgentApprovalInput}, hex.
214
- *
215
- * Hashed rather than stored verbatim because the record persists and is shown
216
- * to a human, while these are the **raw** arguments — the ones the record's
217
- * own `input` field is redacted precisely to keep out of storage. The hash
218
- * binds the approval without keeping the secret.
219
- *
220
- * Async because `crypto.subtle` is: it is the one digest available unchanged
221
- * on every runtime the framework targets (Bun, Node, Workers), and the gate is
222
- * async already.
129
+ * {@link canonicalizeAgentApprovalInput}, hex. Hashed rather than stored
130
+ * verbatim because these are the **raw** arguments while the record persists
131
+ * and is shown to a human. Async because `crypto.subtle` is — the one digest
132
+ * available unchanged on Bun, Node and Workers.
223
133
  */
224
134
  export declare function agentApprovalFingerprint(input: Record<string, unknown>): Promise<string>;
225
135
  /** What {@link buildAgentApprovalRequest} needs beyond the clock. */
@@ -234,62 +144,41 @@ export interface AgentApprovalRequestInput {
234
144
  ttlMs?: number;
235
145
  }
236
146
  /**
237
- * Derive a new pending record.
238
- *
239
- * `now` is a parameter for the reason `toAuditRecord`'s is: the caller that
147
+ * Derive a new pending record. `now` is a parameter because the caller that
240
148
  * creates a record also decides whether an existing one has expired, and two
241
- * clock reads can disagree — a record stamped a millisecond after the instant
242
- * its own expiry was measured against.
243
- *
244
- * The id comes from `crypto.randomUUID()` rather than a parameter, which is
245
- * not the same compromise: an id needs no seam to be testable, since the
246
- * caller reads it straight off the returned record, and threading one in from
247
- * every call site would invite two of them to generate ids differently.
149
+ * clock reads can disagree. The id comes from `crypto.randomUUID()` rather than
150
+ * a parameter: the caller reads it off the returned record, and threading one
151
+ * in would invite two call sites to generate ids differently.
248
152
  */
249
153
  export declare function buildAgentApprovalRequest(request: AgentApprovalRequestInput, now: Date): AgentApprovalRequest;
250
154
  /**
251
- * Whether a record has passed its expiry at `now`.
252
- *
253
- * An unparseable `expiresAt` counts as expired. The alternative — treating a
254
- * date the framework cannot read as "not expired yet" — is a store bug that
255
- * fails open into a permanent approval, and this is the one direction of error
256
- * that cannot be noticed from the outside.
155
+ * Whether a record has passed its expiry at `now`. An unparseable `expiresAt`
156
+ * counts as expired: treating a date the framework cannot read as "not expired
157
+ * yet" fails open into a permanent approval, and that is the one direction of
158
+ * error nothing outside can notice.
257
159
  */
258
160
  export declare function agentApprovalExpiredAt(request: AgentApprovalRequest, now: Date): boolean;
259
161
  /**
260
- * The record's status as of `now`, with expiry applied.
261
- *
262
- * Expiry is derived here rather than filtered by the store on purpose: a store
263
- * that judged it would be a second copy of the rule, and the copy that fails
162
+ * The record's status as of `now`, with expiry applied. Derived here rather
163
+ * than filtered by the store: a second copy of the rule is the one that fails
264
164
  * open — a store that forgets to compare, or compares in local time, hands out
265
- * an approval granted last month and nothing anywhere reports it. A resolved
266
- * record keeps its resolution: a rejection does not become an expiry, and an
267
- * approval that was already spent is reported by `consumedAt`, not by this.
165
+ * an approval granted last month and nothing reports it. A resolved record
166
+ * keeps its resolution.
268
167
  */
269
168
  export declare function agentApprovalStatusAt(request: AgentApprovalRequest, now: Date): AgentApprovalStatus;
270
169
  /**
271
- * Whether this record authorizes a call at `now`: approved, unexpired, and
272
- * not already spent.
273
- *
274
- * All three are checked here, in framework code, rather than trusted to the
275
- * store's query — see {@link AgentApprovalStore.findMatch}. `consumedAt` is
276
- * checked even though `findMatch` promises unconsumed records, because the
277
- * single-use guarantee must not rest on an application's SQL: the *atomic*
278
- * half of it is `consume`'s compare-and-set, and this is the cheap half.
170
+ * Whether this record authorizes a call at `now`: approved, unexpired, and not
171
+ * already spent. All three are checked in framework code rather than trusted to
172
+ * the store's query; `consumedAt` too, because the single-use guarantee must
173
+ * not rest on an application's SQL — `consume`'s compare-and-set is the atomic
174
+ * half of it, this is the cheap half.
279
175
  */
280
176
  export declare function agentApprovalUsableAt(request: AgentApprovalRequest, now: Date): boolean;
281
177
  /**
282
- * Whether `principal` may be told anything at all about `request`.
283
- *
284
- * The scope rule of `guren.approval_status` (RFC 0016 §5.4): a caller reads
285
- * the status only of a request it created. Without it the tool is a way to
286
- * enumerate other principals' pending actions — an agent could walk ids and
287
- * learn what a colleague is waiting to have approved, which is both the
288
- * content of the request and the fact that it exists.
289
- *
290
- * A record this returns `false` for must be answered *exactly* as an unknown
291
- * id is. Any difference between the two answers — a distinct message, a
292
- * different error shape, a slower path — is the enumeration the rule forbids,
293
- * reintroduced.
178
+ * Whether `principal` may be told anything at all about `request` — the scope
179
+ * rule of `guren.approval_status` (RFC 0016 §5.4): a caller reads only the
180
+ * status of a request it created, or an agent could walk ids and enumerate
181
+ * other principals' pending actions. A `false` here must be answered *exactly*
182
+ * as an unknown id is: any difference in message, shape or timing reintroduces it.
294
183
  */
295
184
  export declare function agentApprovalVisibleTo(request: AgentApprovalRequest, principal: AgentPrincipal | null): boolean;
@@ -2,63 +2,35 @@
2
2
  * The one place an agent audit event is announced: to the configured sink, and
3
3
  * to the application's event listeners.
4
4
  *
5
- * Here rather than in a protocol adapter because it has two readers and will
6
- * grow more. `@guren/plugin-mcp` builds one at boot and binds it into the
7
- * container; `guren tool:call` resolves that binding and records the `'cli'`
8
- * surface through the very same function. A second copy is how one surface
9
- * comes to swallow a sink failure the other warns about, or to keep calling a
10
- * sink as an event listener after the other stopped — and the evidence of
11
- * either would be a trail that is quietly missing a surface.
12
- *
13
- * Its own module so it can be exercised without an endpoint. The alternative
14
- * is a closure inside the plugin's `boot`, reachable only by standing up a
15
- * server and making a real tool call — which is worth doing once, and is the
16
- * wrong price for the several cases that matter here (a sink that throws, a
17
- * sink beside a listener that throws, a sink with no event manager at all).
5
+ * Here rather than in a protocol adapter because it has two readers —
6
+ * `@guren/plugin-mcp` binds one into the container at boot, `guren tool:call`
7
+ * resolves that binding for the `'cli'` surface. A second copy is how one
8
+ * surface comes to swallow a sink failure the other warns about. Its own module
9
+ * so it can be exercised without standing up an endpoint.
18
10
  */
19
11
  import type { AgentToolDenied, AgentToolInvoked } from './events.js';
20
12
  import type { EventManager } from '../events/index.js';
21
13
  import { type AgentAuditRecord } from './audit.js';
22
14
  /**
23
15
  * The container service an application's audit emitter is published under
24
- * (`ServiceBindings['agent.audit']`).
25
- *
26
- * A constant rather than a literal at each site, because this is the first
27
- * binding written by one package and read by another that cannot import it:
28
- * `@guren/plugin-mcp` binds it, `@guren/cli` resolves it, and neither depends
29
- * on the other. Two literals that drifted would break the wiring *silently* —
30
- * the CLI would resolve nothing and record nothing, which reads exactly like
31
- * an application that configured no trail. That is the one failure this
32
- * feature exists to prevent, so it may not be spelled twice.
16
+ * (`ServiceBindings['agent.audit']`). A constant because `@guren/plugin-mcp`
17
+ * binds it and `@guren/cli` resolves it, and neither depends on the other; two
18
+ * drifted literals would break the wiring *silently* — the CLI recording
19
+ * nothing reads exactly like an application that configured no trail.
33
20
  */
34
21
  export declare const AGENT_AUDIT_BINDING = "agent.audit";
35
22
  /** What an application hands each audit event to. */
36
23
  export type AgentAuditSink = (record: AgentAuditRecord) => void | Promise<void>;
37
24
  /**
38
- * What every agent surface calls to record one invocation or one denial.
39
- *
40
- * Named because it is a container binding (`'agent.audit'`) as well as a return
41
- * value: a caller resolving it has to be able to say what it expects to find.
25
+ * What every agent surface calls to record one invocation or one denial. Named
26
+ * because it is a container binding (`'agent.audit'`) as well as a return value.
42
27
  */
43
28
  export type AgentAuditEmitter = (event: AgentToolInvoked | AgentToolDenied) => void;
44
29
  /**
45
- * Build the function a surface calls for every invocation and denial.
46
- *
47
- * **The sink is called directly, not subscribed as a listener**, and that is
48
- * the whole reason this function exists rather than an `events.on(...)` pair.
49
- * `EventManager.emit` awaits its listeners in priority order inside a bare
50
- * `for` loop, so the first one to throw ends the loop and every listener after
51
- * it never runs. An unrelated application listener registered at a higher
52
- * priority would then silence the audit trail, and the only evidence an
53
- * operator would have of that is an empty file. A record of what agents did
54
- * cannot be contingent on what else the application happens to listen for.
55
- *
56
- * The events are still emitted, unchanged, for every consumer that
57
- * legitimately is a listener — RFC 0016 §5.2's "forward them wherever you
58
- * already forward events" is untouched.
59
- *
60
- * Neither half may fail the tool call it is recording, so both are caught. The
61
- * sink's failure is *warned* rather than swallowed: an audit sink dropping
62
- * records in silence is precisely the failure this feature exists to prevent.
30
+ * **The sink is called directly, not subscribed as a listener**:
31
+ * `EventManager.emit` awaits listeners in a bare `for` loop, so one unrelated
32
+ * application listener throwing would silence the trail. The events are still
33
+ * emitted for genuine listeners (RFC 0016 §5.2). Neither half may fail the call
34
+ * it records: both are caught, the sink's failure warned rather than swallowed.
63
35
  */
64
36
  export declare function createAuditEmitter(sink: AgentAuditSink | undefined, events: EventManager | undefined, now?: () => Date): AgentAuditEmitter;
@@ -1,25 +1,12 @@
1
1
  /**
2
2
  * The agent audit record (RFC 0016 §5.2): one invocation or one denial, in the
3
3
  * one shape a sink writes as a line and `guren tool:log` reads back.
4
- *
5
- * Declarations and pure derivation only. Nothing here opens a file or reads a
6
- * clock — {@link toAuditRecord} takes the instant as an argument — because
7
- * this module is reachable from every runtime the framework targets, including
8
- * the ones with no filesystem, and because a record builder that timestamped
9
- * itself could not be pinned by a test. *Where* records go is a sink's
10
- * decision, made once by the application (`@guren/plugin-mcp`'s `audit`
11
- * option); this module only says what one looks like.
12
- *
13
- * **Redaction is the emitter's contract, and nothing here may re-run it.**
14
- * `AgentToolInvoked.arguments` arrives having already been through
15
- * `redactAgentArguments`, exactly as `events.ts` states, and this module
16
- * carries it across verbatim. Masking again here would install a second,
17
- * quieter redaction rule beside the real one — the two would drift, and
18
- * nothing reading a record could tell which of them produced a mask it is
19
- * looking at. That is the reasoning `events.ts` used to refuse redacting on
20
- * construction, and it holds one layer down without change. A sink that wants
21
- * different masking changes the route's `.agent({ redact })`, which is the
22
- * one place the rule lives.
4
+ * Declarations and pure derivation only — {@link toAuditRecord} takes the
5
+ * instant as an argument — because this module is reachable from runtimes with
6
+ * no filesystem, and a self-timestamping builder cannot be pinned by a test.
7
+ * **Redaction is the emitter's contract:** `AgentToolInvoked.arguments` arrives
8
+ * already through `redactAgentArguments` and is carried verbatim; different
9
+ * masking belongs in the route's `.agent({ redact })`.
23
10
  */
24
11
  import type { AgentPrincipal, AgentSurface, AgentToolDenialReason, AgentToolDenied, AgentToolInvoked } from './events.js';
25
12
  /**
@@ -55,49 +42,26 @@ export interface AgentAuditDeniedRecord extends AgentAuditRecordBase {
55
42
  reason: AgentToolDenialReason;
56
43
  }
57
44
  /**
58
- * One line of the audit trail.
59
- *
60
- * A union rather than one interface with optional fields, so a record with a
61
- * `reason` *and* a `status` cannot be written down: the two outcomes disagree
62
- * about what happened, and a shape that admits both would let a sink emit that
63
- * contradiction and a reader believe it.
45
+ * One line of the audit trail. A union rather than one interface with optional
46
+ * fields, so a record with a `reason` *and* a `status` cannot be written down:
47
+ * the two outcomes disagree about what happened, and a shape admitting both
48
+ * would let a sink emit that contradiction and a reader believe it.
64
49
  */
65
50
  export type AgentAuditRecord = AgentAuditInvokedRecord | AgentAuditDeniedRecord;
66
51
  /**
67
- * Derive the record for one audit event.
68
- *
69
- * `now` is a parameter rather than a `Date.now()` inside: the sink writing
70
- * this record also picks the dated file it lands in, and two clock reads can
71
- * disagree across a midnight boundary — a record stamped just before it,
72
- * filed just after. One read, used for both.
73
- *
74
- * The two events are told apart structurally, not with `instanceof`. The event
75
- * classes cross a package boundary that this repo resolves twice — `@guren/cli`
76
- * and the plugins reach `@guren/server` through its `dist`, a test inside
77
- * `packages/server` through `src` — so an `instanceof` here would answer
78
- * `false` for a genuine event constructed on the other side of that seam, and
79
- * would do it by mislabelling the record rather than by failing.
52
+ * Derive the record for one audit event. `now` is a parameter because the sink
53
+ * writing the record also picks the dated file it lands in, and two clock reads
54
+ * can disagree across midnight. The two events are told apart structurally, not
55
+ * with `instanceof`: the event classes cross a boundary this repo resolves twice
56
+ * (`dist` for the CLI and plugins, `src` inside `packages/server`).
80
57
  */
81
58
  export declare function toAuditRecord(event: AgentToolInvoked | AgentToolDenied, now: Date): AgentAuditRecord;
82
59
  /**
83
- * Read one line of an audit file back, or `null` if it is not a record.
84
- *
85
- * The one parser on the read side. A caller that hand-rolled a second would be
86
- * the reader half of the drift this whole feature is built to avoid, and would
87
- * be the half that fails silently: a record it stops recognising reads as an
88
- * empty trail.
89
- *
90
- * Returning `null` rather than throwing is what makes the reader usable
91
- * against a file that is being appended to right now. The last line of such a
92
- * file is routinely a *partial* record — an append is not atomic — and a blank
93
- * line is what a file ends with. Neither is corruption, and neither should
94
- * take down a command whose whole job is to show what the earlier lines say.
95
- *
96
- * Extra keys are ignored, deliberately: the file sink writes through
97
- * `DailyFileChannel`, whose JSON format wraps the record in a log envelope
98
- * (`timestamp`, `level`, `message`). Tolerating that envelope is what lets the
99
- * sink reuse the channel's rotation and retention instead of reimplementing
100
- * both, and the record's own fields are unambiguous beside it.
60
+ * Read one line of an audit file back, or `null` if it is not a record. The one
61
+ * parser on the read side; a second would fail silently, since a record it
62
+ * stops recognising reads as an empty trail. `null` rather than a throw: a file
63
+ * being appended to routinely ends in a partial or blank line. Extra keys are
64
+ * ignored because `DailyFileChannel`'s JSON format wraps the record in a log envelope.
101
65
  */
102
66
  export declare function parseAuditRecord(line: string): AgentAuditRecord | null;
103
67
  export {};