@guren/server 2.14.0 → 2.16.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.
- package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
- package/dist/{Hash-CzrwKeDp.js → Hash-D2DFd8xX.js} +12 -57
- package/dist/{HttpException-BkS3euNG.js → HttpException-BlQ2yEmT.js} +2 -79
- package/dist/{Job-BVT813DO.js → Job-DxQK8h3P.js} +24 -179
- package/dist/{McpServiceProvider-BawsYjgN.js → McpServiceProvider-nNcbCIQX.js} +11 -20
- package/dist/{Random-DbIJ22KQ.js → Random-S0OvCuR8.js} +9 -106
- package/dist/agent/AgentApprovalRequested.d.ts +31 -0
- package/dist/agent/approval.d.ts +184 -0
- package/dist/agent/audit-emitter.d.ts +36 -0
- package/dist/agent/audit.d.ts +67 -0
- package/dist/agent/derive.d.ts +32 -66
- package/dist/agent/dispatch.d.ts +53 -63
- package/dist/agent/events.d.ts +11 -19
- package/dist/agent/meta-tools.d.ts +34 -0
- package/dist/agent/public.d.ts +14 -0
- package/dist/agent/public.js +2 -0
- package/dist/agent/redact.d.ts +16 -38
- package/dist/agent/scopes.d.ts +23 -69
- package/dist/auth/AuthManager.d.ts +19 -40
- package/dist/auth/AuthenticatableModel.d.ts +2 -2
- package/dist/auth/SessionGuard.d.ts +0 -1
- package/dist/auth/TokenGuard.d.ts +6 -26
- package/dist/auth/api-token.d.ts +16 -148
- package/dist/auth/context.d.ts +5 -10
- package/dist/auth/email-verification.d.ts +29 -127
- package/dist/auth/index.js +1 -1
- package/dist/auth/oauth/index.d.ts +35 -57
- package/dist/auth/password/DefaultHasher.d.ts +9 -5
- package/dist/auth/password/PasswordHasher.d.ts +7 -0
- package/dist/auth/password/hash-format.d.ts +11 -0
- package/dist/auth/password-reset.d.ts +16 -42
- package/dist/auth/providers/ModelUserProvider.d.ts +3 -4
- package/dist/auth/providers/UserProvider.d.ts +4 -4
- package/dist/auth/signed-token.d.ts +18 -0
- package/dist/auth/types.d.ts +9 -32
- package/dist/auth/utils.d.ts +6 -27
- package/dist/{auth-BSUc14CD.js → auth-CbdPH4Cd.js} +252 -496
- package/dist/authorization/Gate.d.ts +9 -145
- package/dist/authorization/Policy.d.ts +6 -53
- package/dist/authorization/index.js +1 -1
- package/dist/authorization/middleware.d.ts +16 -62
- package/dist/authorization/types.d.ts +8 -64
- package/dist/{authorization-CdfbCj8J.js → authorization-CdEWZZw3.js} +44 -309
- package/dist/broadcasting/BroadcastManager.d.ts +29 -149
- package/dist/broadcasting/channels/Channel.d.ts +1 -19
- package/dist/broadcasting/channels/PresenceChannel.d.ts +1 -55
- package/dist/broadcasting/channels/PrivateChannel.d.ts +1 -23
- package/dist/broadcasting/drivers/MemoryDriver.d.ts +18 -70
- package/dist/broadcasting/drivers/RedisDriver.d.ts +3 -80
- package/dist/broadcasting/drivers/index.d.ts +1 -1
- package/dist/broadcasting/index.d.ts +1 -1
- package/dist/broadcasting/index.js +1 -1
- package/dist/broadcasting/types.d.ts +7 -88
- package/dist/{broadcasting-BxU-LIfF.js → broadcasting-B5RzB0A2.js} +87 -414
- package/dist/cache/CacheManager.d.ts +8 -62
- package/dist/cache/TaggedCache.d.ts +2 -35
- package/dist/cache/index.js +1 -1
- package/dist/cache/stores/FileStore.d.ts +2 -36
- package/dist/cache/stores/MemoryStore.d.ts +2 -26
- package/dist/cache/stores/RedisStore.d.ts +1 -29
- package/dist/cache/types.d.ts +21 -128
- package/dist/{cache-BYnZf2FR.js → cache-BOOIr324.js} +19 -198
- package/dist/client-C4TEr_Dd.js +9 -0
- package/dist/console/Command.d.ts +17 -126
- package/dist/console/ConsoleKernel.d.ts +2 -74
- package/dist/console/Input.d.ts +5 -113
- package/dist/console/Output.d.ts +3 -99
- package/dist/console/types.d.ts +3 -33
- package/dist/container/Container.d.ts +12 -103
- package/dist/container/ServiceProvider.d.ts +17 -61
- package/dist/container/bindings.d.ts +10 -12
- package/dist/container/defineModule.d.ts +16 -54
- package/dist/container/definePlugin.d.ts +12 -45
- package/dist/container/types.d.ts +2 -34
- package/dist/context-CXk_umpT.js +21 -0
- package/dist/database/Factory.d.ts +4 -57
- package/dist/database/Seeder.d.ts +8 -46
- package/dist/database/SeederRunner.d.ts +3 -33
- package/dist/database/types.d.ts +3 -24
- package/dist/discovery/AutoDiscovery.d.ts +10 -82
- package/dist/dispatch-BAwzftws.js +238 -0
- package/dist/docs-viewer/DocsViewerServiceProvider.d.ts +2 -5
- package/dist/docs-viewer/endpoint.d.ts +5 -11
- package/dist/encryption/Encrypter.d.ts +5 -71
- package/dist/encryption/Hash.d.ts +7 -57
- package/dist/encryption/Random.d.ts +6 -99
- package/dist/encryption/index.js +3 -3
- package/dist/encryption/types.d.ts +10 -72
- package/dist/{encryption-DJtkkhiw.js → encryption-uwP3Di4D.js} +13 -79
- package/dist/{endpoint-D6GIqOpe.js → endpoint-BXipU2Jj.js} +6 -12
- package/dist/endpoint-Dsw3Acvq.js +26 -0
- package/dist/errors/ExceptionHandler.d.ts +3 -90
- package/dist/errors/HttpException.d.ts +2 -79
- package/dist/errors/debug-page.d.ts +3 -17
- package/dist/errors/error-page.d.ts +1 -0
- package/dist/errors/exceptions/AuthenticationException.d.ts +2 -24
- package/dist/errors/exceptions/AuthorizationException.d.ts +1 -24
- package/dist/errors/exceptions/MethodNotAllowedException.d.ts +1 -23
- package/dist/errors/exceptions/NotFoundHttpException.d.ts +1 -27
- package/dist/errors/exceptions/ValidationException.d.ts +2 -43
- package/dist/errors/types.d.ts +1 -25
- package/dist/{errors-BgeOl_DC.js → errors-JpkcCjjn.js} +3 -41
- package/dist/events/Event.d.ts +1 -28
- package/dist/events/EventManager.d.ts +5 -107
- package/dist/events/Listener.d.ts +7 -55
- package/dist/events/builtin.d.ts +0 -24
- package/dist/events/index.js +1 -1
- package/dist/events/types.d.ts +4 -22
- package/dist/{events-aIH_bWRx.js → events-DOmAHDeP.js} +11 -191
- package/dist/facades/index.d.ts +2 -14
- package/dist/health/HealthCheck.d.ts +0 -24
- package/dist/health/HealthManager.d.ts +0 -36
- package/dist/health/checks/CacheCheck.d.ts +2 -17
- package/dist/health/checks/CustomCheck.d.ts +0 -9
- package/dist/health/checks/DatabaseCheck.d.ts +2 -17
- package/dist/health/checks/MemoryCheck.d.ts +3 -12
- package/dist/health/checks/RedisCheck.d.ts +1 -13
- package/dist/health/checks/StorageCheck.d.ts +2 -17
- package/dist/health/index.js +1 -1
- package/dist/health/types.d.ts +4 -24
- package/dist/{health-VWdWXRwh.js → health-DQSvUplL.js} +1 -76
- package/dist/hot-disposables-B5BXqaIH.js +167 -0
- package/dist/hot-reload/hot-disposables.d.ts +22 -74
- package/dist/hot-reload/testing.d.ts +4 -9
- package/dist/http/Application.d.ts +62 -208
- package/dist/http/FormRequest.d.ts +4 -55
- package/dist/http/dev-assets.d.ts +16 -18
- package/dist/http/dev-banner.d.ts +2 -5
- package/dist/http/inertia-assets.d.ts +3 -6
- package/dist/http/middleware/capabilities.d.ts +27 -50
- package/dist/http/middleware/cors.d.ts +4 -29
- package/dist/http/middleware/csp.d.ts +2 -25
- package/dist/http/middleware/csrf.d.ts +20 -95
- package/dist/http/middleware/detect-locale.d.ts +7 -27
- package/dist/http/middleware/force-https.d.ts +6 -24
- package/dist/http/middleware/host-authorization.d.ts +2 -12
- package/dist/http/middleware/loopback-guard.d.ts +15 -33
- package/dist/http/middleware/rate-limit.d.ts +29 -126
- package/dist/http/middleware/redirect-safety.d.ts +2 -20
- package/dist/http/middleware/request-id.d.ts +1 -14
- package/dist/http/middleware/request-logging.d.ts +2 -13
- package/dist/http/middleware/response-headers.d.ts +5 -13
- package/dist/http/middleware/security-headers.d.ts +2 -16
- package/dist/http/middleware/session.d.ts +15 -34
- package/dist/http/middleware/validation-errors-cookie.d.ts +7 -18
- package/dist/http/middleware/validation.d.ts +8 -63
- package/dist/http/public-assets.d.ts +14 -0
- package/dist/http/request.d.ts +49 -48
- package/dist/http/resources/CursorPaginator.d.ts +5 -64
- package/dist/http/resources/Paginator.d.ts +7 -84
- package/dist/http/resources/Resource.d.ts +9 -65
- package/dist/http/resources/ResourceCollection.d.ts +5 -39
- package/dist/http/resources/types.d.ts +10 -30
- package/dist/http/static-documents.d.ts +21 -0
- package/dist/http/validation/Validator.d.ts +25 -85
- package/dist/http/validation/rules.d.ts +48 -147
- package/dist/http/validation/types.d.ts +16 -61
- package/dist/http/vite-assets.d.ts +5 -28
- package/dist/http/vite-dev-server.d.ts +6 -9
- package/dist/http/vite-manifest.d.ts +19 -33
- package/dist/i18n/I18nManager.d.ts +12 -78
- package/dist/i18n/Translator.d.ts +3 -54
- package/dist/i18n/index.js +1 -1
- package/dist/i18n/loaders/JsonLoader.d.ts +4 -31
- package/dist/i18n/loaders/MemoryLoader.d.ts +1 -21
- package/dist/i18n/pluralization.d.ts +4 -13
- package/dist/i18n/types.d.ts +17 -69
- package/dist/{i18n-mcWi7LCd.js → i18n-Cg1aajRP.js} +31 -225
- package/dist/index.d.ts +13 -4
- package/dist/index.js +1036 -3080
- package/dist/internal/agent-preflight.d.ts +9 -21
- package/dist/internal/request.d.ts +10 -17
- package/dist/internal/request.js +2 -2
- package/dist/internal/route-path.d.ts +9 -21
- package/dist/internal/route-path.js +9 -21
- package/dist/internal/zod-compat.d.ts +55 -122
- package/dist/internal/zod-compat.js +39 -70
- package/dist/internal/zod-json-schema.d.ts +18 -54
- package/dist/internal/zod-json-schema.js +46 -123
- package/dist/jsx-runtime.d.ts +3 -8
- package/dist/lambda/index.d.ts +17 -79
- package/dist/lambda/index.js +11 -59
- package/dist/logging/LogManager.d.ts +1 -51
- package/dist/logging/Logger.d.ts +8 -47
- package/dist/logging/channels/ConsoleChannel.d.ts +1 -3
- package/dist/logging/channels/DailyFileChannel.d.ts +1 -5
- package/dist/logging/channels/FileChannel.d.ts +1 -3
- package/dist/logging/daily-file-path.d.ts +15 -0
- package/dist/logging/index.d.ts +1 -0
- package/dist/logging/index.js +2 -2
- package/dist/logging/types.d.ts +13 -45
- package/dist/{logging-CPaRMuPP.js → logging-zOY1XCtq.js} +83 -129
- package/dist/{loopback-guard-D0Kc7-xc.js → loopback-guard-DT9gHF0F.js} +41 -92
- package/dist/mail/Mail.d.ts +10 -106
- package/dist/mail/MailManager.d.ts +2 -60
- package/dist/mail/index.js +1 -1
- package/dist/mail/transports/LogTransport.d.ts +1 -4
- package/dist/mail/transports/MemoryTransport.d.ts +1 -63
- package/dist/mail/transports/ResendTransport.d.ts +1 -23
- package/dist/mail/transports/SmtpTransport.d.ts +1 -31
- package/dist/mail/types.d.ts +28 -150
- package/dist/{mail-DfEfSQEr.js → mail-76DWy9lj.js} +31 -289
- package/dist/mcp/McpServiceProvider.d.ts +4 -10
- package/dist/mcp/create-mcp-server.d.ts +25 -57
- package/dist/mcp/endpoint.d.ts +12 -36
- package/dist/mcp/index.js +1 -1
- package/dist/mvc/Controller.d.ts +46 -253
- package/dist/mvc/Router.d.ts +50 -129
- package/dist/mvc/inertia/InertiaEngine.d.ts +18 -48
- package/dist/mvc/inertia/shared.d.ts +6 -19
- package/dist/mvc/mount-route.d.ts +2 -6
- package/dist/mvc/view.d.ts +1 -2
- package/dist/notifications/Notification.d.ts +8 -75
- package/dist/notifications/NotificationManager.d.ts +15 -88
- package/dist/notifications/channels/DatabaseChannel.d.ts +1 -41
- package/dist/notifications/channels/MailChannel.d.ts +2 -31
- package/dist/notifications/channels/MemoryChannel.d.ts +2 -62
- package/dist/notifications/channels/SlackChannel.d.ts +3 -48
- package/dist/notifications/index.js +1 -1
- package/dist/notifications/notifiable-type.d.ts +3 -6
- package/dist/notifications/registry.d.ts +8 -27
- package/dist/notifications/types.d.ts +16 -53
- package/dist/{notifications-BGqmUNZ8.js → notifications-okWFs9ly.js} +37 -335
- package/dist/providers/AuthServiceProvider.d.ts +1 -3
- package/dist/providers/AuthorizationServiceProvider.d.ts +2 -3
- package/dist/providers/BroadcastServiceProvider.d.ts +1 -3
- package/dist/providers/CacheServiceProvider.d.ts +1 -3
- package/dist/providers/EncryptionServiceProvider.d.ts +1 -3
- package/dist/providers/ErrorServiceProvider.d.ts +1 -4
- package/dist/providers/EventServiceProvider.d.ts +1 -3
- package/dist/providers/HealthServiceProvider.d.ts +1 -3
- package/dist/providers/I18nServiceProvider.d.ts +6 -10
- package/dist/providers/InertiaServiceProvider.d.ts +1 -4
- package/dist/providers/LogServiceProvider.d.ts +1 -3
- package/dist/providers/MailServiceProvider.d.ts +1 -3
- package/dist/providers/NotificationServiceProvider.d.ts +1 -3
- package/dist/providers/OAuthServiceProvider.d.ts +1 -3
- package/dist/providers/QueueServiceProvider.d.ts +1 -3
- package/dist/providers/SchedulingServiceProvider.d.ts +1 -3
- package/dist/providers/StorageServiceProvider.d.ts +1 -3
- package/dist/queue/FailedJobReporter.d.ts +1 -24
- package/dist/queue/Job.d.ts +12 -99
- package/dist/queue/QueueManager.d.ts +6 -57
- package/dist/queue/Worker.d.ts +4 -65
- package/dist/queue/drivers/MemoryDriver.d.ts +3 -44
- package/dist/queue/drivers/RedisDriver.d.ts +7 -65
- package/dist/queue/drivers/SqsDriver.d.ts +6 -57
- package/dist/queue/drivers/SyncDriver.d.ts +10 -13
- package/dist/queue/index.js +2 -2
- package/dist/queue/types.d.ts +10 -92
- package/dist/{queue-CXrRK85G.js → queue-CcXCjuJI.js} +32 -260
- package/dist/redis/RedisApiTokenStore.d.ts +4 -56
- package/dist/redis/RedisEmailVerificationStore.d.ts +4 -37
- package/dist/redis/RedisOAuthStateStore.d.ts +2 -10
- package/dist/redis/RedisPasswordResetStore.d.ts +4 -37
- package/dist/redis/RedisRateLimitStore.d.ts +16 -49
- package/dist/redis/RedisSessionStore.d.ts +3 -44
- package/dist/redis/client.d.ts +2 -32
- package/dist/redis/index.js +47 -232
- package/dist/redis/redis-values.d.ts +6 -12
- package/dist/redis/scan-keys.d.ts +1 -4
- package/dist/request-CLOYytGP.js +68 -0
- package/dist/runtime/index.d.ts +2 -0
- package/dist/runtime/index.js +108 -74
- package/dist/scheduling/CronParser.d.ts +0 -29
- package/dist/scheduling/Schedule.d.ts +1 -153
- package/dist/scheduling/ScheduledTask.d.ts +0 -31
- package/dist/scheduling/Scheduler.d.ts +0 -70
- package/dist/scheduling/index.js +1 -1
- package/dist/scheduling/types.d.ts +4 -65
- package/dist/{scheduling-CPiEdtQd.js → scheduling-C6tcOtUl.js} +2 -287
- package/dist/storage/StorageManager.d.ts +0 -48
- package/dist/storage/drivers/LocalDriver.d.ts +1 -25
- package/dist/storage/drivers/MemoryDriver.d.ts +5 -35
- package/dist/storage/drivers/S3Driver.d.ts +6 -36
- package/dist/storage/drivers/s3-acl.d.ts +5 -10
- package/dist/storage/index.js +1 -1
- package/dist/storage/types.d.ts +27 -265
- package/dist/{storage-TLD9t0Q2.js → storage-BB59f07j.js} +17 -157
- package/dist/support/contained-path.d.ts +10 -20
- package/dist/support/error-polyfill.d.ts +4 -6
- package/dist/support/expiry.d.ts +17 -33
- package/dist/support/expiry.js +17 -33
- package/dist/support/import-map.d.ts +3 -7
- package/dist/support/inertia-defaults.d.ts +5 -10
- package/dist/support/redirect-target.d.ts +4 -6
- package/dist/support/stack-frames.d.ts +11 -50
- package/dist/support/trim-slashes.d.ts +4 -7
- package/dist/support/warn-once.d.ts +2 -6
- package/dist/{trim-slashes-ZJ_VsY5s.js → trim-slashes-BLY9hKAa.js} +4 -7
- package/dist/{vite-manifest-BGfWbPYp.js → vite-manifest-CTQp-SOo.js} +34 -58
- package/package.json +6 -2
- package/dist/client-Dd7vLcqp.js +0 -27
- package/dist/context-DoD0c7J_.js +0 -26
- package/dist/endpoint-D-20PiHY.js +0 -46
- package/dist/hot-disposables-WsTX2ySN.js +0 -281
- package/dist/request-CRVuIiQr.js +0 -78
package/dist/agent/derive.d.ts
CHANGED
|
@@ -1,42 +1,25 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Turns registered route definitions into agent tools (RFC 0016 §2).
|
|
3
3
|
*
|
|
4
|
-
*
|
|
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
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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
|
|
27
|
-
* shared walker's type
|
|
28
|
-
*
|
|
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
|
|
35
|
-
*
|
|
36
|
-
*
|
|
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
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
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
|
|
85
|
-
*
|
|
86
|
-
*
|
|
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 —
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
* the runtime
|
|
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}
|
|
125
|
-
*
|
|
126
|
-
*
|
|
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
|
|
137
|
-
*
|
|
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
|
|
146
|
-
*
|
|
147
|
-
*
|
|
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
|
/**
|
package/dist/agent/dispatch.d.ts
CHANGED
|
@@ -1,15 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The dispatch contract (RFC 0016 §3): a tool call re-enters the application
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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';
|
|
8
|
+
import type { AgentSurface } from './events.js';
|
|
13
9
|
export interface BuildToolRequestOptions {
|
|
14
10
|
/**
|
|
15
11
|
* Origin the synthesized URL is built on. Never leaves the process — the
|
|
@@ -30,52 +26,55 @@ export interface BuildToolRequestOptions {
|
|
|
30
26
|
* stops before the handler. Only routes declaring `.agent()` honour it.
|
|
31
27
|
*/
|
|
32
28
|
preflight?: boolean;
|
|
29
|
+
/**
|
|
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.
|
|
35
|
+
*/
|
|
36
|
+
surface?: AgentSurface;
|
|
33
37
|
}
|
|
34
38
|
/**
|
|
35
39
|
* The argument-level spelling of a preflight request (RFC 0016 §5.4), for a
|
|
36
|
-
* surface whose callers pass flat arguments rather than dispatch options.
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
* ask through `BuildToolRequestOptions.preflight`. A surface that adopts this
|
|
41
|
-
* key owns the stripping — it is an instruction to the adapter, not a field of
|
|
42
|
-
* any route's contract, and forwarding it would fail the very validation the
|
|
43
|
-
* 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.
|
|
44
44
|
*/
|
|
45
45
|
export declare const PREFLIGHT_ARGUMENT = "_preflight";
|
|
46
46
|
export type BuiltToolRequest = {
|
|
47
47
|
request: Request;
|
|
48
|
-
}
|
|
48
|
+
} | ToolRequestBuildFailure;
|
|
49
|
+
/** The ways `buildToolRequest` refuses to build — no HTTP has happened. */
|
|
50
|
+
export type ToolRequestBuildFailure =
|
|
49
51
|
/** Path parameters the call did not supply — the URL cannot be built. */
|
|
50
|
-
|
|
52
|
+
{
|
|
51
53
|
missing: string[];
|
|
52
54
|
}
|
|
53
55
|
/**
|
|
54
56
|
* Path parameter values that are URL dot-segments (`.` / `..`). Rejected,
|
|
55
|
-
* never substituted: `encodeURIComponent` leaves a dot untouched
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
* `..`; every other separator (`/`, `\`) survives `encodeURIComponent`
|
|
60
|
-
* 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.
|
|
61
61
|
*/
|
|
62
62
|
| {
|
|
63
63
|
invalidPath: string[];
|
|
64
64
|
};
|
|
65
65
|
/**
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* GET and HEAD force everything into the query
|
|
77
|
-
* `Request` refuses a body
|
|
78
|
-
* route is a contract defect this adapter cannot repair.
|
|
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.
|
|
70
|
+
*/
|
|
71
|
+
export declare function describeBuildFailure(failure: ToolRequestBuildFailure): string;
|
|
72
|
+
/**
|
|
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.
|
|
79
78
|
*/
|
|
80
79
|
export declare function buildToolRequest(tool: DerivedAgentTool, args: Record<string, unknown>, options?: BuildToolRequestOptions): BuiltToolRequest;
|
|
81
80
|
/** An MCP tool result, shaped for the SDK's CallToolResult. */
|
|
@@ -88,36 +87,27 @@ export interface ToolCallOutcome {
|
|
|
88
87
|
isError?: boolean;
|
|
89
88
|
/** The HTTP status the dispatch resolved to, for the audit event. */
|
|
90
89
|
status: number;
|
|
90
|
+
/**
|
|
91
|
+
* The response carried the preflight verdict header, so this is the seam's
|
|
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.
|
|
96
|
+
*/
|
|
97
|
+
preflightVerdict?: boolean;
|
|
91
98
|
}
|
|
92
99
|
/**
|
|
93
100
|
* Whether the tool advertises an object output schema — the only kind MCP
|
|
94
|
-
* lists, and
|
|
95
|
-
* `structuredContent`.
|
|
96
|
-
*
|
|
97
|
-
* results ride as text. `describeTool` and `mapToolResponse` must agree on
|
|
98
|
-
* 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.
|
|
99
104
|
*/
|
|
100
105
|
export declare function advertisesStructuredOutput(tool: DerivedAgentTool): boolean;
|
|
101
106
|
/**
|
|
102
|
-
* Map the application's response onto an MCP tool result (RFC 0016 §3.4)
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
* no `outputSchema` — unwrap and schema are mutually exclusive by
|
|
108
|
-
* derivation, so the advertised shape can never disagree with the result.
|
|
109
|
-
* - 204 / 3xx → a status line naming the Location; not an error.
|
|
110
|
-
* - 4xx / 5xx → `isError: true` carrying the exception handler's JSON body:
|
|
111
|
-
* a 422's `{ message, errors }` is an application-level failure the agent
|
|
112
|
-
* should read, not a protocol error.
|
|
113
|
-
* - non-JSON → capped text.
|
|
114
|
-
*
|
|
115
|
-
* One MCP invariant overrides the table: a *non-error* result for a tool that
|
|
116
|
-
* advertises an object `outputSchema` must carry `structuredContent`, or the
|
|
117
|
-
* SDK client rejects it after the route has already run. A success response
|
|
118
|
-
* that yields no object to put there (204, 3xx, non-JSON, a non-object body)
|
|
119
|
-
* contradicts the route's own declared output, so it becomes an `isError`
|
|
120
|
-
* result naming the mismatch — which the SDK exempts from the rule — rather
|
|
121
|
-
* 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.
|
|
122
112
|
*/
|
|
123
113
|
export declare function mapToolResponse(tool: DerivedAgentTool, response: Response): Promise<ToolCallOutcome>;
|
package/dist/agent/events.d.ts
CHANGED
|
@@ -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
|
|
5
|
-
* API.
|
|
4
|
+
* wherever it already forwards events.
|
|
6
5
|
*
|
|
7
|
-
* Declarations only. Nothing here emits
|
|
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
|
|
11
|
-
*
|
|
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
|
/**
|
|
@@ -44,23 +40,19 @@ export declare class AgentToolInvoked extends Event {
|
|
|
44
40
|
readonly surface: AgentSurface;
|
|
45
41
|
/**
|
|
46
42
|
* The invocation arguments **already redacted** by the emitter (see the
|
|
47
|
-
* module header). Assigned in the body rather than
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
* perfectly legal property name.
|
|
43
|
+
* module header). Assigned in the body rather than as a constructor parameter
|
|
44
|
+
* property: `arguments` is not a legal binding identifier in strict mode,
|
|
45
|
+
* though it is a legal property name.
|
|
51
46
|
*/
|
|
52
47
|
readonly arguments: Record<string, unknown>;
|
|
53
48
|
constructor(principal: AgentPrincipal | null, tool: string, redactedArguments: Record<string, unknown>, status: number, durationMs: number, surface: AgentSurface);
|
|
54
49
|
}
|
|
55
50
|
/**
|
|
56
51
|
* Why a tool invocation was refused before it reached the route handler.
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
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.
|
|
52
|
+
* Deliberately no `'policy'`: `Gate` policies evaluate *inside* the dispatched
|
|
53
|
+
* request, so a policy denial is an execution that returned 403. These are
|
|
54
|
+
* exactly the checks the adapter runs before synthesizing the request, which is
|
|
55
|
+
* also why a denial carries no HTTP status — no HTTP happened.
|
|
64
56
|
*/
|
|
65
57
|
export type AgentToolDenialReason = 'auth' | 'scope' | 'approval' | 'rate-limit';
|
|
66
58
|
/**
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The names a protocol adapter may add to an application's tool catalogue on
|
|
3
|
+
* its own, and which an application route therefore may not claim (RFC 0016
|
|
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.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
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).
|
|
17
|
+
*/
|
|
18
|
+
export declare const PREFLIGHT_TOOL_NAME = "guren.preflight";
|
|
19
|
+
/**
|
|
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.
|
|
25
|
+
*/
|
|
26
|
+
export declare const APPROVAL_STATUS_TOOL_NAME = "guren.approval_status";
|
|
27
|
+
/** Every meta-tool name an adapter may occupy. */
|
|
28
|
+
export declare const RESERVED_AGENT_TOOL_NAMES: readonly string[];
|
|
29
|
+
/**
|
|
30
|
+
* Whether a tool name belongs to the framework rather than the application.
|
|
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.
|
|
33
|
+
*/
|
|
34
|
+
export declare function isReservedAgentToolName(name: string): boolean;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The published entry of `@guren/server/agent` (mirrored as
|
|
3
|
+
* `@guren/core/agent`): the half of the agent surface an *out-of-process*
|
|
4
|
+
* dispatcher needs — a browser tab running WebMCP, a CLI, a test harness.
|
|
5
|
+
* Two rules keep it importable there. Pure Web API only (`Request`,
|
|
6
|
+
* `Response`, `Headers`, `URLSearchParams`): no `node:` import, no Bun global,
|
|
7
|
+
* no DOM, so it loads under SSR too. And types only from `./derive` —
|
|
8
|
+
* re-exporting a *value* would silently pull `Router` and the authorization
|
|
9
|
+
* middleware into a client bundle.
|
|
10
|
+
*/
|
|
11
|
+
export { advertisesStructuredOutput, buildToolRequest, describeBuildFailure, mapToolResponse, PREFLIGHT_ARGUMENT, } from './dispatch.js';
|
|
12
|
+
export type { BuildToolRequestOptions, BuiltToolRequest, ToolCallOutcome, ToolRequestBuildFailure, } from './dispatch.js';
|
|
13
|
+
export type { AgentToolInputSource, AgentToolSchema, DerivedAgentTool, DerivedAgentToolAnnotations, DerivedAgentToolExposure, } from './derive.js';
|
|
14
|
+
export type { AgentSurface } from './events.js';
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import { a as mapToolResponse, i as describeBuildFailure, n as advertisesStructuredOutput, r as buildToolRequest, t as PREFLIGHT_ARGUMENT } from "../dispatch-BAwzftws.js";
|
|
2
|
+
export { PREFLIGHT_ARGUMENT, advertisesStructuredOutput, buildToolRequest, describeBuildFailure, mapToolResponse };
|
package/dist/agent/redact.d.ts
CHANGED
|
@@ -1,22 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Argument masking for the agent audit trail (RFC 0016 §5.2).
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* *contains* a fragment, and that applies to the declared `redact` entries
|
|
11
|
-
* too, not just the built-ins. So `redact: ['id']` also masks `userId`, and
|
|
12
|
-
* the built-in `session` masks `sessionCount`. Over-redaction is the safe
|
|
13
|
-
* direction for a log: a masked field that did not need masking costs a
|
|
14
|
-
* debugging round trip, an unmasked credential costs a rotation.
|
|
15
|
-
*
|
|
16
|
-
* The walk is total for the same reason the derivation is: it runs while
|
|
17
|
-
* *recording* what happened, including a denial taken before the route's own
|
|
18
|
-
* validation, so it must not be the thing that throws. A cycle and a payload
|
|
19
|
-
* nested past {@link MAX_DEPTH} both terminate with a marker.
|
|
2
|
+
* Argument masking for the agent audit trail (RFC 0016 §5.2). Two sources,
|
|
3
|
+
* unioned: a fixed list of sensitive key *fragments* every application gets,
|
|
4
|
+
* and the route's own `.agent({ redact })`. A key matches when its lowercased
|
|
5
|
+
* name *contains* a fragment, declared entries included — `redact: ['id']` also
|
|
6
|
+
* masks `userId`. Over-redaction is the safe direction: a needless mask costs a
|
|
7
|
+
* debugging round trip, an unmasked credential costs a rotation. The walk is
|
|
8
|
+
* total because it runs while recording a denial taken before validation: a
|
|
9
|
+
* cycle and a payload nested past {@link MAX_DEPTH} both terminate with a marker.
|
|
20
10
|
*/
|
|
21
11
|
/**
|
|
22
12
|
* The replacement written in place of a masked value. A string, so a redacted
|
|
@@ -24,10 +14,9 @@
|
|
|
24
14
|
*/
|
|
25
15
|
export declare const AGENT_REDACTED = "[REDACTED]";
|
|
26
16
|
/**
|
|
27
|
-
* Written in place of a value that closes a cycle
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
* you", the other "there is nothing further here to show".
|
|
17
|
+
* Written in place of a value that closes a cycle. Distinct from
|
|
18
|
+
* {@link AGENT_REDACTED} on purpose: one says "we would not show you", the
|
|
19
|
+
* other "there is nothing further here to show".
|
|
31
20
|
*/
|
|
32
21
|
export declare const AGENT_CIRCULAR = "[Circular]";
|
|
33
22
|
/**
|
|
@@ -35,21 +24,10 @@ export declare const AGENT_CIRCULAR = "[Circular]";
|
|
|
35
24
|
*/
|
|
36
25
|
export declare const AGENT_TRUNCATED = "[Truncated]";
|
|
37
26
|
/**
|
|
38
|
-
* Mask the sensitive fields of an agent tool's arguments
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* a `Map`, a `Set`, a class instance) is carried across as the *same
|
|
44
|
-
* reference*, because copying it would need a rule per type and would still
|
|
45
|
-
* get the exotic cases wrong; nothing below such a value is inspected, so a
|
|
46
|
-
* credential hidden inside a class instance is masked only if the key holding
|
|
47
|
-
* that instance matches. Tool arguments arrive as parsed JSON on every
|
|
48
|
-
* surface, where this case does not occur; a caller synthesizing arguments in
|
|
49
|
-
* process is the one that can hit it.
|
|
50
|
-
*
|
|
51
|
-
* @param args The invocation arguments. Walked as a record whatever its
|
|
52
|
-
* prototype, so the return is always a fresh plain object.
|
|
53
|
-
* @param redact Extra key fragments from the route's `.agent({ redact })`.
|
|
27
|
+
* Mask the sensitive fields of an agent tool's arguments; `redact` adds the
|
|
28
|
+
* route's `.agent({ redact })` fragments. Returns a fresh plain object (`args`
|
|
29
|
+
* is walked as a record whatever its prototype), deep only through plain objects
|
|
30
|
+
* and arrays: a `Date`, `Map` or class instance is carried by reference and
|
|
31
|
+
* never inspected, which only an in-process caller can hit (surfaces pass JSON).
|
|
54
32
|
*/
|
|
55
33
|
export declare function redactAgentArguments(args: Record<string, unknown>, redact?: readonly string[]): Record<string, unknown>;
|
package/dist/agent/scopes.d.ts
CHANGED
|
@@ -1,49 +1,19 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The scope grammar an API token's `abilities` use to reach agent tools
|
|
3
|
-
* (RFC 0016 §5.1).
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* -
|
|
10
|
-
* - `tools:read` every tool whose resolved `readOnlyHint` is true
|
|
11
|
-
* - `tools:*` every tool
|
|
12
|
-
* - `tools:<prefix>.*` every tool named `<prefix>.…`
|
|
13
|
-
*
|
|
14
|
-
* **Only `tool:` / `tools:` entries are considered.** Every other ability an
|
|
15
|
-
* `ApiToken` carries — including the store's default `['*']` — is ignored, so
|
|
16
|
-
* it matches nothing. This is the fail-closed half of a deliberate split:
|
|
17
|
-
*
|
|
18
|
-
* - A token issued before agent tools existed, for an app's own API, holds
|
|
19
|
-
* `['*']`. Reading that as "all agent tools" would silently hand every
|
|
20
|
-
* already-issued token the whole agent surface the moment an app declares
|
|
21
|
-
* its first `.agent()` route. Access to the agent surface is granted by an
|
|
22
|
-
* explicit tool scope or not at all (default deny, RFC §5.1); `tools:*` is
|
|
23
|
-
* the explicit way to say "everything".
|
|
24
|
-
* - A malformed entry is likewise ignored here rather than throwing: this
|
|
25
|
-
* module judges an already-issued token, and a token that cannot be parsed
|
|
26
|
-
* must grant less, never more. Rejecting a bad scope belongs to the
|
|
27
|
-
* *issuer* (`token:issue`, a later PR), which runs {@link parseToolScope}
|
|
28
|
-
* over what it was asked for and refuses a `null`.
|
|
29
|
-
*
|
|
30
|
-
* Matching is case-sensitive and entries are not trimmed. A stored ability
|
|
31
|
-
* with stray whitespace is an issuance bug; normalizing it here would make
|
|
32
|
-
* the judge more permissive than the issuer, which is the wrong direction.
|
|
3
|
+
* (RFC 0016 §5.1). Four forms, so a human can read a scope on a consent screen:
|
|
4
|
+
* `tool:<name>`, `tools:read` (every tool whose resolved `readOnlyHint` is
|
|
5
|
+
* true), `tools:*`, `tools:<prefix>.*`. **Only `tool:` / `tools:` entries are
|
|
6
|
+
* considered**, so the store's default `['*']` grants no tool (default deny). A
|
|
7
|
+
* malformed entry is ignored, not thrown: this module judges an issued token and
|
|
8
|
+
* must grant less, never more; rejecting belongs to the issuer, which refuses a
|
|
9
|
+
* `null` from {@link parseToolScope}. Case-sensitive and untrimmed, for the same reason.
|
|
33
10
|
*/
|
|
34
11
|
/**
|
|
35
12
|
* The MCP tool-name grammar (SEP-986), which a `tool:` scope names and a
|
|
36
|
-
* `tools:<prefix>.*` scope
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* `
|
|
40
|
-
* check that fails a build over an illegal tool name. Collapsing the two onto
|
|
41
|
-
* this export is a later change, not this one: the CLI reaches `@guren/server`
|
|
42
|
-
* through `dist/`, so the collapse needs a built server and belongs with the
|
|
43
|
-
* PR that does the build-order work.
|
|
44
|
-
*
|
|
45
|
-
* Note what the charset gives for free: `*` is not in it, so `tool:posts.*`
|
|
46
|
-
* fails the test and needs no special case to be rejected.
|
|
13
|
+
* `tools:<prefix>.*` scope must stay inside. `packages/cli/src/agent-route-check.ts`
|
|
14
|
+
* holds the same pattern; collapsing the two needs a built server, so it waits
|
|
15
|
+
* for the PR doing that build-order work. `*` is not in the charset, so
|
|
16
|
+
* `tool:posts.*` is rejected with no special case.
|
|
47
17
|
*/
|
|
48
18
|
export declare const AGENT_TOOL_NAME_PATTERN: RegExp;
|
|
49
19
|
/** One well-formed scope entry, discriminated by what it grants. */
|
|
@@ -68,10 +38,8 @@ export type ParsedToolScope =
|
|
|
68
38
|
};
|
|
69
39
|
/**
|
|
70
40
|
* The shape a tool has to present to be judged: its name, and whether it
|
|
71
|
-
* resolved to read-only. Deliberately not `DerivedAgentTool
|
|
72
|
-
*
|
|
73
|
-
* them should have to build a whole derived tool to ask a question about two
|
|
74
|
-
* fields. `DerivedAgentTool` is structurally compatible via
|
|
41
|
+
* resolved to read-only. Deliberately not `DerivedAgentTool`, which is
|
|
42
|
+
* structurally compatible via
|
|
75
43
|
* `{ name: tool.toolName, readOnly: tool.annotations.readOnlyHint }`.
|
|
76
44
|
*/
|
|
77
45
|
export interface ScopedTool {
|
|
@@ -79,19 +47,11 @@ export interface ScopedTool {
|
|
|
79
47
|
readOnly: boolean;
|
|
80
48
|
}
|
|
81
49
|
/**
|
|
82
|
-
* Parse one `abilities` entry.
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
* tool-name grammar). Callers cannot tell those apart on purpose: both mean
|
|
88
|
-
* "grants no tool", and a judge that distinguished them would be inventing
|
|
89
|
-
* a third answer for a two-valued question.
|
|
90
|
-
*
|
|
91
|
-
* Note the two reserved `tools:` words are matched before the wildcard form,
|
|
92
|
-
* so a tool family literally named `read.…` is still reachable as
|
|
93
|
-
* `tools:read.*`, while a tool named exactly `read` is reachable only as
|
|
94
|
-
* `tool:read` — the reserved word wins its own spelling.
|
|
50
|
+
* Parse one `abilities` entry. The two reserved `tools:` words are matched
|
|
51
|
+
* before the wildcard form, so a family named `read.…` is still reachable as
|
|
52
|
+
* `tools:read.*` while a tool named exactly `read` is only `tool:read`.
|
|
53
|
+
* @returns The scope, or `null` for both a non-tool entry and a malformed one
|
|
54
|
+
* (`tools:`, `tools:.*`, `tools:*.store`): both mean "grants no tool", on purpose.
|
|
95
55
|
*/
|
|
96
56
|
export declare function parseToolScope(entry: string): ParsedToolScope | null;
|
|
97
57
|
/**
|
|
@@ -100,16 +60,10 @@ export declare function parseToolScope(entry: string): ParsedToolScope | null;
|
|
|
100
60
|
*/
|
|
101
61
|
export declare function scopesAllowTool(abilities: readonly string[], tool: ScopedTool): boolean;
|
|
102
62
|
/**
|
|
103
|
-
* The concrete tool names a token's abilities grant, for the surfaces that
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
* second matcher that walked entries and accumulated names is how a consent
|
|
109
|
-
* screen comes to list a tool the dispatcher then denies — the two answers
|
|
110
|
-
* have to be the same answer, not two implementations of one rule.
|
|
111
|
-
*
|
|
112
|
-
* @returns Names in the order the tools were given, so a caller controls the
|
|
113
|
-
* display order by ordering its input.
|
|
63
|
+
* The concrete tool names a token's abilities grant, for the surfaces that show
|
|
64
|
+
* a human what a scope means: the OAuth consent screen, the `token:issue`
|
|
65
|
+
* confirmation, the issuance-time lint. Literally a filter over
|
|
66
|
+
* {@link scopesAllowTool}, and it must stay one: a second matcher is how a
|
|
67
|
+
* consent screen comes to list a tool the dispatcher then denies. Order of `tools`.
|
|
114
68
|
*/
|
|
115
69
|
export declare function expandToolScopes(abilities: readonly string[], tools: readonly ScopedTool[]): string[];
|