@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,42 +1,25 @@
1
1
  /**
2
2
  * Turns registered route definitions into agent tools (RFC 0016 §2).
3
3
  *
4
- * This is the *one* derivation. The runtime protocol adapters and the CLI's
4
+ * The *one* derivation: the runtime protocol adapters and the CLI's
5
5
  * `.guren/agents.gen.ts` both call it, so a generated manifest and a live MCP
6
- * server can differ only in description richness — never in schemas, names, or
7
- * exposure. Nothing here is restated by hand: the input schema comes from the
8
- * route's own `params`/`query`/`body` contracts through the shared Zod → JSON
9
- * Schema walker, the output schema from `output`, the ability from the
10
- * authorization capability its middleware chain stamped.
11
- *
12
- * Two properties this function keeps deliberately:
13
- *
14
- * - **Total.** Nothing throws and nothing is silently dropped for being
15
- * malformed. A contract this cannot express becomes a warning plus a
16
- * deterministic result, because the same call has to serve a dev server, a
17
- * codegen step, and a production adapter. `guren check` is what turns those
18
- * warnings into a failing build (PR-1c).
19
- * - **Opt-in.** A route becomes a tool only by declaring `.agent()` *and*
20
- * carrying a name. Auto-exposing endpoints is the anti-pattern RFC 0016
21
- * opens by rejecting.
6
+ * server can differ only in description richness. Nothing is restated by hand.
7
+ * Total — an inexpressible contract becomes a warning plus a deterministic
8
+ * result, and `guren check` turns those warnings into a failing build. Opt-in —
9
+ * a route becomes a tool only by declaring `.agent()` *and* carrying a name.
22
10
  */
23
11
  import type { ResourceResponseShape, RouteDefinition } from '../mvc/Router.js';
24
12
  import { type JsonSchemaObject } from '../internal/zod-json-schema.js';
25
13
  /**
26
- * A JSON Schema 2020-12 object as an agent tool advertises it. An alias of the
27
- * shared walker's type rather than a second definition — OpenAPI 3.1's Schema
28
- * Object is the same dialect, and `@guren/openapi` aliases it the same way, so
29
- * one definition serves every surface. The name exists so the internal module
30
- * is not the one a consumer has to import.
14
+ * A JSON Schema 2020-12 object as an agent tool advertises it — an alias of the
15
+ * shared walker's type, which `@guren/openapi` aliases the same way, so one
16
+ * definition serves every surface.
31
17
  */
32
18
  export type AgentToolSchema = JsonSchemaObject;
33
19
  /**
34
- * MCP `ToolAnnotations`, resolved to explicit values — a consumer never has to
35
- * re-apply a default, and `guren check`'s annotation-honesty rule has one
36
- * concrete claim to check the controller against.
37
- *
38
- * These are hints for client UX, not enforcement. Authorization lives in
39
- * policies, scopes, and the approval queue.
20
+ * MCP `ToolAnnotations`, resolved to explicit values so no consumer re-applies
21
+ * a default and `guren check`'s annotation-honesty rule has one concrete claim
22
+ * to check. Hints for client UX, not enforcement.
40
23
  */
41
24
  export interface DerivedAgentToolAnnotations {
42
25
  /** The tool does not modify its environment. */
@@ -62,47 +45,34 @@ export interface DerivedAgentTool {
62
45
  path: string;
63
46
  /**
64
47
  * `agent.description`, else the route's OpenAPI `description`, else its
65
- * `summary`. Absent when the route declares none — nothing is invented here;
66
- * the CLI appends resource type text at codegen time, and `guren check`
67
- * warns about a tool with no description at all.
48
+ * `summary`. Absent when the route declares none — nothing is invented here.
68
49
  */
69
50
  description?: string;
70
51
  /** Merged `params` + `query` + `body`, object root (MCP requires one). */
71
52
  inputSchema: AgentToolSchema;
72
53
  /**
73
54
  * Which contract each advertised input property came from — the inverse of
74
- * the merge, for the adapter that has to take a flat tool call apart again
75
- * and rebuild the HTTP request: `params`/`path` substitute into the URL
76
- * path, `query` joins the query string, `body` lands in the JSON body. The
77
- * schema alone cannot answer this (the merge is flat by design), and an
78
- * adapter guessing by method would put a POST route's `query` keys in the
79
- * body, where `validateQuery` never looks.
55
+ * the merge, for the adapter that rebuilds the HTTP request from a flat tool
56
+ * call. The schema alone cannot answer it, and an adapter guessing by method
57
+ * would put a POST route's `query` keys in the body, where `validateQuery`
58
+ * never looks.
80
59
  */
81
60
  inputSources: Record<string, AgentToolInputSource>;
82
61
  /**
83
62
  * True when the route's `body` schema was not an object and therefore nests
84
- * under a single `body` property (see {@link buildInputSchema}). The
85
- * dispatching adapter must then send `arguments.body` *as* the HTTP body,
86
- * not an object wrapping it — the flat reconstruction would post
87
- * `{ body: [...] }` to a route that validates an array.
63
+ * under a single `body` property. The adapter must then send `arguments.body`
64
+ * *as* the HTTP body: the flat rebuild would post `{ body: [...] }` to a
65
+ * route that validates an array.
88
66
  */
89
67
  inputBodyNested: boolean;
90
68
  /** Present only when the route binds an `output` schema — the one shape validated at runtime. */
91
69
  outputSchema?: AgentToolSchema;
92
70
  /**
93
- * The route's `resource` response hint, as class names — RFC 0016's second
94
- * output rung, carried rather than resolved. `definitions()` has only the
95
- * names; the payload type behind them exists solely in the CLI's AST
96
- * extraction, which is why codegen enriches the description from this and
97
- * the runtime does not.
98
- *
99
- * Absent when the route declares no hint — and, deliberately, whenever the
100
- * route *declares* an `output` schema, whether or not the walker could
101
- * render it. The declaration is what the runtime validates against, so it
102
- * outranks the hint; carrying both would leave two descriptions of one
103
- * response with nothing keeping them in agreement, and a route whose
104
- * `output` the walker cannot express would advertise the *unvalidated* one
105
- * while the enforced contract silently vanished.
71
+ * The route's `resource` response hint, as class names — carried rather than
72
+ * resolved: the payload type behind them exists only in the CLI's AST
73
+ * extraction. Absent when the route declares no hint, and deliberately also
74
+ * whenever it declares an `output` schema, whether or not the walker could
75
+ * render it — the declaration is what the runtime validates against.
106
76
  */
107
77
  resource?: ResourceResponseShape;
108
78
  annotations: DerivedAgentToolAnnotations;
@@ -121,11 +91,9 @@ export interface DerivedAgentTool {
121
91
  expose: DerivedAgentToolExposure;
122
92
  /**
123
93
  * What could not be expressed while deriving *this* tool, unprefixed. The
124
- * same lines appear in {@link DeriveAgentToolsResult.warnings} prefixed with
125
- * the tool name; that aggregate is for printing, this field is for anything
126
- * that needs to know which tool a warning belongs to. Attributing by parsing
127
- * the prefix back off would couple every consumer to a message format
128
- * nothing states. Empty for a tool that derived cleanly.
94
+ * same lines appear prefixed in {@link DeriveAgentToolsResult.warnings};
95
+ * attributing by parsing the prefix back off would couple every consumer to a
96
+ * message format nothing states.
129
97
  */
130
98
  warnings: string[];
131
99
  }
@@ -133,18 +101,16 @@ export interface DeriveAgentToolsResult {
133
101
  tools: DerivedAgentTool[];
134
102
  /**
135
103
  * Everything the derivation could not express, one line each, prefixed with
136
- * the tool (or the route, for a route that could not become one). Non-fatal
137
- * by construction — see the module header. Per-tool lines are also on the
138
- * tool itself ({@link DerivedAgentTool.warnings}), which is what a consumer
139
- * needing attribution should read.
104
+ * the tool (or the route). Non-fatal by construction. Per-tool lines are also
105
+ * on the tool itself, which is what a consumer needing attribution reads.
140
106
  */
141
107
  warnings: string[];
142
108
  }
143
109
  /**
144
110
  * Where a merged input property came from — collision reporting inside the
145
- * merge, request reconstruction outside it ({@link DerivedAgentTool.inputSources}).
146
- * `params` and `path` both mean URL substitution to an adapter; they stay
147
- * distinct because a warning should name the schema the author actually wrote.
111
+ * merge, request reconstruction outside it. `params` and `path` both mean URL
112
+ * substitution to an adapter; they stay distinct so a warning names the schema
113
+ * the author actually wrote.
148
114
  */
149
115
  export type AgentToolInputSource = 'params' | 'path' | 'query' | 'body';
150
116
  /**
@@ -1,13 +1,8 @@
1
1
  /**
2
- * The dispatch contract (RFC 0016 §3): a tool call re-enters the application
3
- * as a real HTTP request, so validation, policies, and middleware run exactly
4
- * once, in the app — never re-implemented here.
5
- *
6
- * This module is pure request/response plumbing: it rebuilds an HTTP request
7
- * from a flat tool call and maps the app's response onto an MCP tool result.
8
- * It never validates arguments (the route does, and the MCP client already
9
- * saw the JSON Schema) and never decides authorization (the gate and the
10
- * app's policies do).
2
+ * The dispatch contract (RFC 0016 §3): a tool call re-enters the application as
3
+ * a real HTTP request, so validation, policies and middleware run exactly once,
4
+ * in the app. Pure request/response plumbing — it never validates arguments and
5
+ * never decides authorization.
11
6
  */
12
7
  import type { DerivedAgentTool } from './derive.js';
13
8
  import type { AgentSurface } from './events.js';
@@ -32,34 +27,20 @@ export interface BuildToolRequestOptions {
32
27
  */
33
28
  preflight?: boolean;
34
29
  /**
35
- * Which protocol surface the call arrived on, announced to the application
36
- * as `X-Guren-Agent-Surface`. Defaults to `'mcp'`, the surface that was the
37
- * only one when this header was introduced, so every existing caller keeps
38
- * sending exactly what it sent before.
39
- *
40
- * The header is informational and, in the framework, write-only: nothing
41
- * here reads it back. It is there for an *application* that wants to tell
42
- * an in-browser session call from a bearer-token one, and it borrows the
43
- * audit trail's vocabulary ({@link AgentSurface}) so the two agree — but
44
- * the trail's own `surface` comes from the adapter that recorded it, not
45
- * from this header. Nothing must ever authorize on it: any client sets any
46
- * header it likes, so a surface can never relax a check.
30
+ * Which protocol surface the call arrived on, announced as
31
+ * `X-Guren-Agent-Surface`; defaults to `'mcp'`. Informational and write-only
32
+ * here — it borrows the audit trail's vocabulary ({@link AgentSurface}), but
33
+ * the trail's own `surface` comes from the adapter. Nothing may authorize on
34
+ * it: any client sets any header it likes.
47
35
  */
48
36
  surface?: AgentSurface;
49
37
  }
50
38
  /**
51
39
  * The argument-level spelling of a preflight request (RFC 0016 §5.4), for a
52
- * surface whose callers pass flat arguments rather than dispatch options.
53
- *
54
- * No adapter strips it today, because none accepts it. Every surface that
55
- * reaches the seam asks through `BuildToolRequestOptions.preflight` instead:
56
- * `guren tool:call` and `@guren/testing` from their own flags, and MCP from
57
- * the `guren.preflight` companion tool, which takes the target tool's name
58
- * and arguments rather than smuggling a directive through them (RFC 0016
59
- * §5.4 — a verdict conforms to no route's output schema, so it needs a tool
60
- * of its own). A surface that adopts this key owns the stripping — it is an
61
- * instruction to the adapter, not a field of any route's contract, and
62
- * forwarding it would fail the very validation the caller asked to rehearse.
40
+ * surface whose callers pass flat arguments rather than dispatch options. No
41
+ * adapter accepts it today — every surface asks through
42
+ * `BuildToolRequestOptions.preflight`. A surface adopting it owns the stripping:
43
+ * it is an instruction to the adapter, not a field of any route's contract.
63
44
  */
64
45
  export declare const PREFLIGHT_ARGUMENT = "_preflight";
65
46
  export type BuiltToolRequest = {
@@ -73,39 +54,27 @@ export type ToolRequestBuildFailure =
73
54
  }
74
55
  /**
75
56
  * Path parameter values that are URL dot-segments (`.` / `..`). Rejected,
76
- * never substituted: `encodeURIComponent` leaves a dot untouched, and the
77
- * `Request` URL parser then collapses the segment — so `{ name: '..' }` on
78
- * `/files/:name/meta` would reach `/meta`, a route the scope check never
79
- * saw. The only ASCII segments the WHATWG parser normalizes are `.` and
80
- * `..`; every other separator (`/`, `\`) survives `encodeURIComponent`
81
- * percent-encoded, so this is the complete set.
57
+ * never substituted: `encodeURIComponent` leaves a dot untouched and the URL
58
+ * parser then collapses the segment, so `{ name: '..' }` on `/files/:name/meta`
59
+ * would reach `/meta`, a route the scope check never saw. `.` and `..` are
60
+ * the only ASCII segments the WHATWG parser normalizes, so this set is complete.
82
61
  */
83
62
  | {
84
63
  invalidPath: string[];
85
64
  };
86
65
  /**
87
- * The agent-facing diagnosis of a {@link ToolRequestBuildFailure}.
88
- *
89
- * One function rather than a string per adapter: the same tool is reachable
90
- * from several surfaces (App MCP, WebMCP, `guren tool:call`), and an agent
91
- * that reads a different diagnosis depending on which one it reached would
92
- * be debugging the client instead of its own call.
66
+ * The agent-facing diagnosis of a {@link ToolRequestBuildFailure}. One function
67
+ * rather than a string per adapter: the same tool is reachable from several
68
+ * surfaces, and a diagnosis that varied by surface would have an agent
69
+ * debugging the client instead of its own call.
93
70
  */
94
71
  export declare function describeBuildFailure(failure: ToolRequestBuildFailure): string;
95
72
  /**
96
- * Rebuild the HTTP request a tool call describes.
97
- *
98
- * The flat argument object is taken apart along `tool.inputSources` — the
99
- * derivation's own record of which contract each property came from — so a
100
- * POST route's `query` keys land in the query string where `validateQuery`
101
- * reads them, not in the body. Keys the derivation never advertised are
102
- * forwarded anyway (body for body-carrying methods, query otherwise): the
103
- * route's validator is the one place that rejects them, and dropping them
104
- * here would make this a second, quieter validator.
105
- *
106
- * GET and HEAD force everything into the query string whatever its source —
107
- * `Request` refuses a body on those methods, and a `body` schema on a GET
108
- * route is a contract defect this adapter cannot repair.
73
+ * Rebuild the HTTP request a tool call describes. The flat argument object is
74
+ * taken apart along `tool.inputSources`, so a POST route's `query` keys land
75
+ * where `validateQuery` reads them; unadvertised keys are forwarded for the
76
+ * route's validator to reject. GET and HEAD force everything into the query
77
+ * string: `Request` refuses a body there, and a GET `body` schema is a defect.
109
78
  */
110
79
  export declare function buildToolRequest(tool: DerivedAgentTool, args: Record<string, unknown>, options?: BuildToolRequestOptions): BuiltToolRequest;
111
80
  /** An MCP tool result, shaped for the SDK's CallToolResult. */
@@ -120,46 +89,25 @@ export interface ToolCallOutcome {
120
89
  status: number;
121
90
  /**
122
91
  * The response carried the preflight verdict header, so this is the seam's
123
- * answer and not the route's own output.
124
- *
125
- * Carried here because `mapToolResponse` is the only place that sees the
126
- * header — an outcome has no headers — and the fact is otherwise lost. A
127
- * caller that re-derived it by looking for a `preflight` field in the body
128
- * would read an ordinary route whose output happens to carry that field as a
129
- * rehearsal that never ran, which is the exact confusion the header was
130
- * introduced to prevent.
92
+ * answer and not the route's own output. Carried here because
93
+ * `mapToolResponse` is the only place that sees the header; a caller
94
+ * re-deriving it from a `preflight` field in the body would read an ordinary
95
+ * route as a rehearsal that never ran.
131
96
  */
132
97
  preflightVerdict?: boolean;
133
98
  }
134
99
  /**
135
100
  * Whether the tool advertises an object output schema — the only kind MCP
136
- * lists, and therefore the only kind that obliges a success result to carry
137
- * `structuredContent`. A route whose `output` is an array or primitive is not
138
- * advertised as structured (MCP `outputSchema` must be an object), so its
139
- * results ride as text. `describeTool` and `mapToolResponse` must agree on
140
- * this exact predicate, or one advertises a schema the other cannot satisfy.
101
+ * lists, and so the only kind obliging a success result to carry
102
+ * `structuredContent`. `describeTool` and `mapToolResponse` must agree on this
103
+ * exact predicate, or one advertises a schema the other cannot satisfy.
141
104
  */
142
105
  export declare function advertisesStructuredOutput(tool: DerivedAgentTool): boolean;
143
106
  /**
144
- * Map the application's response onto an MCP tool result (RFC 0016 §3.4).
145
- *
146
- * - 2xx JSON object → serialized text, plus `structuredContent` when the tool
147
- * advertises an object `outputSchema` (the one shape the route validated).
148
- * - 2xx Inertia page JSON → unwrapped to `page.props`, only for a tool with
149
- * no `outputSchema` — unwrap and schema are mutually exclusive by
150
- * derivation, so the advertised shape can never disagree with the result.
151
- * - 204 / 3xx → a status line naming the Location; not an error.
152
- * - 4xx / 5xx → `isError: true` carrying the exception handler's JSON body:
153
- * a 422's `{ message, errors }` is an application-level failure the agent
154
- * should read, not a protocol error.
155
- * - non-JSON → capped text.
156
- *
157
- * One MCP invariant overrides the table: a *non-error* result for a tool that
158
- * advertises an object `outputSchema` must carry `structuredContent`, or the
159
- * SDK client rejects it after the route has already run. A success response
160
- * that yields no object to put there (204, 3xx, non-JSON, a non-object body)
161
- * contradicts the route's own declared output, so it becomes an `isError`
162
- * result naming the mismatch — which the SDK exempts from the rule — rather
163
- * than a protocol fault the agent cannot interpret.
107
+ * Map the application's response onto an MCP tool result (RFC 0016 §3.4): 2xx
108
+ * JSON → text (+ `structuredContent` for an object `outputSchema`); Inertia page
109
+ * JSON → `page.props`; 204/3xx → status line, not an error; 4xx/5xx → `isError`
110
+ * with the handler's body; other → capped text. An object-`outputSchema` success
111
+ * lacking an object becomes `isError`: the SDK client rejects it after the route ran.
164
112
  */
165
113
  export declare function mapToolResponse(tool: DerivedAgentTool, response: Response): Promise<ToolCallOutcome>;
@@ -1,16 +1,12 @@
1
1
  /**
2
2
  * The audit trail of the agent surface (RFC 0016 §5.2): every tool invocation
3
3
  * and every denial, as framework events, so an application forwards them
4
- * wherever it already forwards events instead of learning a second logging
5
- * API.
4
+ * wherever it already forwards events.
6
5
  *
7
- * Declarations only. Nothing here emits — the dispatch path does, once, at
8
- * the one place that knows the verdict — and nothing here redacts:
6
+ * Declarations only. Nothing here emits or redacts:
9
7
  * {@link AgentToolInvoked.arguments} is a *contract* that the emitter has
10
- * already run the arguments through `redactAgentArguments`. An event class
11
- * that redacted on construction would give a second, quieter redaction rule
12
- * beside the real one, and a listener has no way to tell a masked payload
13
- * from an unmasked one.
8
+ * already run them through `redactAgentArguments`; redacting on construction
9
+ * would be a second, quieter rule beside the real one.
14
10
  */
15
11
  import { Event } from '../events/Event.js';
16
12
  /**
@@ -25,11 +21,13 @@ export interface AgentPrincipal {
25
21
  abilities?: string[];
26
22
  }
27
23
  /**
28
- * The protocol surface an invocation arrived on. `'mcp'` is the application's
29
- * own MCP endpoint, `'dev-mcp'` the development one, `'cli'` a
30
- * `guren tool:call`, `'webmcp'` an in-browser session-authenticated call.
24
+ * The protocol surface an invocation arrived on: `'mcp'` the application's own
25
+ * endpoint, `'dev-mcp'` the development one, `'cli'` a `guren tool:call`,
26
+ * `'webmcp'` an in-browser session call, `'durable'` an agent the application
27
+ * hosts itself (RFC 0017 §4). Every consumer enumerates these as a *total* map,
28
+ * so adding one fails to compile rather than silently failing to parse.
31
29
  */
32
- export type AgentSurface = 'mcp' | 'dev-mcp' | 'cli' | 'webmcp';
30
+ export type AgentSurface = 'mcp' | 'dev-mcp' | 'cli' | 'webmcp' | 'durable';
33
31
  /**
34
32
  * Emitted when an agent tool invocation completed — successfully or not.
35
33
  * `status` carries the HTTP status the dispatch resolved to, so an error
@@ -44,23 +42,19 @@ export declare class AgentToolInvoked extends Event {
44
42
  readonly surface: AgentSurface;
45
43
  /**
46
44
  * The invocation arguments **already redacted** by the emitter (see the
47
- * module header). Assigned in the body rather than declared as a
48
- * constructor parameter property: `arguments` is not a legal binding
49
- * identifier in strict mode, which every ES module is, though it is a
50
- * perfectly legal property name.
45
+ * module header). Assigned in the body rather than as a constructor parameter
46
+ * property: `arguments` is not a legal binding identifier in strict mode,
47
+ * though it is a legal property name.
51
48
  */
52
49
  readonly arguments: Record<string, unknown>;
53
50
  constructor(principal: AgentPrincipal | null, tool: string, redactedArguments: Record<string, unknown>, status: number, durationMs: number, surface: AgentSurface);
54
51
  }
55
52
  /**
56
53
  * Why a tool invocation was refused before it reached the route handler.
57
- *
58
- * Deliberately no `'policy'`: `Gate` policies evaluate *inside* the
59
- * dispatched request, so a policy denial is an execution that returned 403 —
60
- * an {@link AgentToolInvoked} with that status — not an adapter-level
61
- * refusal. The reasons here are exactly the checks the adapter runs before
62
- * synthesizing the request, which is also why a denial carries no HTTP
63
- * status: no HTTP happened.
54
+ * Deliberately no `'policy'`: `Gate` policies evaluate *inside* the dispatched
55
+ * request, so a policy denial is an execution that returned 403. These are
56
+ * exactly the checks the adapter runs before synthesizing the request, which is
57
+ * also why a denial carries no HTTP status — no HTTP happened.
64
58
  */
65
59
  export type AgentToolDenialReason = 'auth' | 'scope' | 'approval' | 'rate-limit';
66
60
  /**
@@ -0,0 +1,118 @@
1
+ /**
2
+ * The adapter-level checks a tool call passes before any HTTP request is
3
+ * synthesized (RFC 0016 §5); what happens *inside* the dispatched request is
4
+ * the application's verdict, reported as an invocation with its HTTP status and
5
+ * never re-judged here. {@link gateToolCall} is synchronous and free of side
6
+ * effects because `tools/list` calls it for every tool on every listing — an
7
+ * approval check there would create a pending record and notify approvers once
8
+ * per tool per client connect. The approval half is {@link gateApproval},
9
+ * reached only from the call path.
10
+ */
11
+ import { type AgentApprovalRequest, type AgentApprovalStore } from './approval.js';
12
+ import type { DerivedAgentTool } from './derive.js';
13
+ import type { AgentPrincipal, AgentToolDenialReason } from './events.js';
14
+ export type GateVerdict = {
15
+ allowed: true;
16
+ } | {
17
+ allowed: false;
18
+ reason: AgentToolDenialReason;
19
+ message: string;
20
+ /**
21
+ * Rendered as the error result's JSON content. Only approval refusals
22
+ * carry one: a caller told "this is pending" needs the id to poll with.
23
+ * Measured against the SDK client, an `isError: true` result keeps its
24
+ * `content` even for a tool declaring an `outputSchema` — which is what
25
+ * makes a pending answer expressible on this protocol (RFC 0016 §5.4).
26
+ */
27
+ body?: Record<string, unknown>;
28
+ };
29
+ /**
30
+ * How an unconfigured approval queue is described when no surface says it
31
+ * better. The pipeline cannot know whether it was reached over MCP, from a
32
+ * durable agent or from a test harness, and naming one surface's configuration
33
+ * call would send most readers to a package they do not install. A surface that
34
+ * knows says so through {@link ScopeGateOptions.configureHint}.
35
+ */
36
+ export declare const DEFAULT_APPROVAL_CONFIGURE_HINT = "an approval queue on the invocation pipeline (approvals: { store, notify })";
37
+ /**
38
+ * Whose scopes a refusal names when no surface says it better. Neutral because
39
+ * a scope denial is not always about a token: a durable agent's principal is
40
+ * minted from its registration and holds no credential, so naming "the token's
41
+ * scopes" would send its operator looking for a token to widen.
42
+ */
43
+ export declare const DEFAULT_SCOPE_SUBJECT = "The caller's scopes";
44
+ /** What {@link gateToolCall} and {@link gatePreflight} need beyond the scopes. */
45
+ export interface ScopeGateOptions {
46
+ /** Whether an approval queue exists to turn a gated call into a request. */
47
+ approvalsConfigured?: boolean;
48
+ /**
49
+ * How *this* surface configures a queue, named in the fail-closed refusal —
50
+ * `'mcpPlugin({ approvals: { store, notify } })'` for the App MCP endpoint,
51
+ * else {@link DEFAULT_APPROVAL_CONFIGURE_HINT}. The trailing period belongs
52
+ * to the sentence: pass the expression, not a sentence.
53
+ */
54
+ configureHint?: string;
55
+ /**
56
+ * What a scope refusal calls the thing whose scopes fell short — `"The
57
+ * token's scopes"` on a bearer surface, else {@link DEFAULT_SCOPE_SUBJECT}.
58
+ * The subject of a sentence completed with " do not grant the tool …", so
59
+ * pass a noun phrase and no trailing punctuation.
60
+ */
61
+ scopeSubject?: string;
62
+ }
63
+ /** What {@link gateApproval} needs to answer for one call. */
64
+ export interface ApprovalGateContext {
65
+ store: AgentApprovalStore;
66
+ principal: AgentPrincipal | null;
67
+ /** How long a new pending record stays answerable. */
68
+ ttlMs?: number;
69
+ now: () => Date;
70
+ /**
71
+ * `redactAgentArguments(args, tool.redact)`, passed in so this module runs
72
+ * exactly one redaction rule and defines none.
73
+ */
74
+ redact(args: Record<string, unknown>): Record<string, unknown>;
75
+ /**
76
+ * Called once, only for a record this call created, and **never awaited**: a
77
+ * channel that is down must not fail the call or lose the persisted record.
78
+ * Implementations report their own failures; see {@link notifyApprovers}.
79
+ */
80
+ notify(request: AgentApprovalRequest): void;
81
+ }
82
+ /**
83
+ * Wrap the application's `notify` so a failure can neither fail the tool call nor
84
+ * lose the record: it is already persisted when this runs, so a dead channel costs
85
+ * an approver an email, not a request. The failure is warned about with the request
86
+ * id, which is what finds the record sitting there unannounced. Both shapes are
87
+ * caught — a synchronous throw and a rejected promise.
88
+ */
89
+ export declare function notifyApprovers(notify: (request: AgentApprovalRequest) => void | Promise<void>): (request: AgentApprovalRequest) => void;
90
+ /**
91
+ * Scope and approval, in that order — a caller learns a tool needs approval only
92
+ * once its token could invoke it, so an unauthorized probe cannot map which
93
+ * tools are approval-gated. `approvalsConfigured` is synchronous because
94
+ * `tools/list` asks it: with a queue an approval-gated tool *is* callable (the
95
+ * call queues) and belongs in the catalogue; without one, listing it invites a refusal.
96
+ */
97
+ export declare function gateToolCall(tool: DerivedAgentTool, abilities: readonly string[], options?: ScopeGateOptions): GateVerdict;
98
+ /**
99
+ * The approval half (RFC 0016 §5.4 item 4). One lookup on tool + *raw* arguments'
100
+ * fingerprint + principal: a pending or rejected match refuses without a second
101
+ * record or notification (polling by re-calling would page approvers per poll);
102
+ * a rejection blocks only while its record is live. Consumed *before* dispatch,
103
+ * one attempt not one success: else concurrent calls pass and a crash is replayable.
104
+ */
105
+ export declare function gateApproval(tool: DerivedAgentTool, args: Record<string, unknown>, context: ApprovalGateContext): Promise<GateVerdict>;
106
+ /**
107
+ * The scope half alone — what `guren.preflight` checks before rehearsing a call
108
+ * (RFC 0016 §5.4). Checking requires the *same* scope as calling, or the
109
+ * companion becomes a probe of tools the token cannot call. Approval is not
110
+ * applied: a rehearsal executes nothing, and approval gates an ability rather
111
+ * than knowledge; never reaching {@link gateApproval}, it files and pages nothing.
112
+ */
113
+ export declare function gatePreflight(tool: DerivedAgentTool, abilities: readonly string[], options?: ScopeGateOptions): GateVerdict;
114
+ /** The two fields the scope grammar judges a tool by. */
115
+ export declare function scopedShape(tool: DerivedAgentTool): {
116
+ name: string;
117
+ readOnly: boolean;
118
+ };
@@ -1,62 +1,34 @@
1
1
  /**
2
2
  * The names a protocol adapter may add to an application's tool catalogue on
3
3
  * its own, and which an application route therefore may not claim (RFC 0016
4
- * §5.4).
5
- *
6
- * This is the one rule, with two readers. `@guren/plugin-mcp` adds
7
- * `guren.preflight` to the catalogue it serves; `guren check` fails a route
8
- * whose `.agent()` tool name would collide with it. Restating the string in
9
- * either place is how the two drift: the check would keep passing a route
10
- * whose tool the endpoint has already shadowed, and `tools/list` would carry
11
- * two tools with one name — which an MCP client rejects wholesale, so the
12
- * collision costs the *entire* catalogue, not the one tool.
13
- *
14
- * It lives beside the derivation rather than in the plugin because the check
15
- * cannot import the plugin (the CLI does not depend on it, and an app that
16
- * never installs App MCP is still checked), and the plugin must not restate a
17
- * name the check is enforcing.
18
- *
19
- * The list stays deliberately short. Every entry is a name taken away from
20
- * applications, and the `guren.` prefix is not reserved wholesale for the
21
- * same reason: reserving a namespace nothing occupies fails routes over a
22
- * collision that does not exist.
4
+ * §5.4). One rule, two readers: `@guren/plugin-mcp` adds `guren.preflight` to
5
+ * the catalogue it serves, `guren check` fails a route whose tool name
6
+ * collides; the CLI cannot import the plugin, hence beside the derivation. A
7
+ * `tools/list` carrying two tools with one name is rejected wholesale by an MCP
8
+ * client, so a collision costs the *entire* catalogue. The `guren.` prefix is
9
+ * not reserved wholesale: that would fail routes over collisions that do not exist.
23
10
  */
24
11
  /**
25
- * The preflight companion tool (RFC 0016 §5.4).
26
- *
27
- * Preflight cannot be an *argument* of the tool being checked on MCP: a tool
28
- * advertising an `outputSchema` must answer with `structuredContent`
29
- * conforming to it unless the result is an error, and a verdict conforms to
30
- * no route's output. So the verdict needs a tool of its own, with its own
31
- * output schema — one meta-tool for the whole catalogue, not one companion
32
- * per tool, which would double the catalogue against §5.5's own
33
- * catalogue-quality rule.
12
+ * The preflight companion tool (RFC 0016 §5.4). Preflight cannot be an
13
+ * *argument* of the tool being checked: a tool advertising an `outputSchema`
14
+ * must answer with conforming `structuredContent` unless the result is an
15
+ * error, and a verdict conforms to no route's output. One meta-tool for the
16
+ * whole catalogue, not one companion per tool (§5.5).
34
17
  */
35
18
  export declare const PREFLIGHT_TOOL_NAME = "guren.preflight";
36
19
  /**
37
- * The approval-status companion tool (RFC 0016 §5.4 item 4).
38
- *
39
- * A tool declaring `approval: 'required'` answers its first call with a
40
- * pending record rather than an execution, and the caller is handed a request
41
- * id. Something has to be able to say what became of that id, and it cannot be
42
- * the gated tool itself for the reason preflight cannot be an argument of one:
43
- * a status is not that route's output, and a tool advertising an `outputSchema`
44
- * may not answer with a different shape of success.
45
- *
46
- * A second meta-tool rather than a mode of the first: `guren.preflight`
47
- * rehearses a call and answers a verdict, this reads a record and answers its
48
- * state. Folding both under one name would mean one tool whose output schema
49
- * is the union of two unrelated shapes, which is the thing a schema is for
50
- * preventing.
20
+ * The approval-status companion tool (RFC 0016 §5.4 item 4). A caller handed a
21
+ * request id needs something that can say what became of it, and the gated tool
22
+ * cannot: a status is not that route's output. A second meta-tool rather than a
23
+ * mode of the first, so neither output schema is the union of two unrelated
24
+ * shapes.
51
25
  */
52
26
  export declare const APPROVAL_STATUS_TOOL_NAME = "guren.approval_status";
53
27
  /** Every meta-tool name an adapter may occupy. */
54
28
  export declare const RESERVED_AGENT_TOOL_NAMES: readonly string[];
55
29
  /**
56
30
  * Whether a tool name belongs to the framework rather than the application.
57
- *
58
- * Case-sensitive, like every other comparison the tool-name grammar makes:
59
- * MCP tool names are matched literally, so `Guren.Preflight` is a different
60
- * tool and reserving it would take a name away for nothing.
31
+ * Case-sensitive: MCP tool names are matched literally, so `Guren.Preflight` is
32
+ * a different tool and reserving it would take a name away for nothing.
61
33
  */
62
34
  export declare function isReservedAgentToolName(name: string): boolean;