@vinkius-core/mcp-fusion 2.9.0 → 2.12.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 (172) hide show
  1. package/dist/cli/fusion.d.ts +3 -0
  2. package/dist/cli/fusion.d.ts.map +1 -1
  3. package/dist/cli/fusion.js +125 -3
  4. package/dist/cli/fusion.js.map +1 -1
  5. package/dist/cli/templates/config.js +3 -3
  6. package/dist/cli/templates/config.js.map +1 -1
  7. package/dist/cli/templates/constants.d.ts +1 -1
  8. package/dist/cli/templates/constants.d.ts.map +1 -1
  9. package/dist/cli/templates/constants.js +1 -1
  10. package/dist/cli/templates/constants.js.map +1 -1
  11. package/dist/cli/templates/core.js +5 -5
  12. package/dist/cli/templates/middleware.d.ts +1 -1
  13. package/dist/cli/templates/middleware.d.ts.map +1 -1
  14. package/dist/cli/templates/middleware.js +16 -13
  15. package/dist/cli/templates/middleware.js.map +1 -1
  16. package/dist/cli/templates/readme.d.ts.map +1 -1
  17. package/dist/cli/templates/readme.js +14 -18
  18. package/dist/cli/templates/readme.js.map +1 -1
  19. package/dist/cli/templates/tools.d.ts +4 -0
  20. package/dist/cli/templates/tools.d.ts.map +1 -1
  21. package/dist/cli/templates/tools.js +26 -29
  22. package/dist/cli/templates/tools.js.map +1 -1
  23. package/dist/cli/templates/vectors/database.d.ts.map +1 -1
  24. package/dist/cli/templates/vectors/database.js +14 -19
  25. package/dist/cli/templates/vectors/database.js.map +1 -1
  26. package/dist/cli/templates/vectors/oauth.d.ts.map +1 -1
  27. package/dist/cli/templates/vectors/oauth.js +4 -5
  28. package/dist/cli/templates/vectors/oauth.js.map +1 -1
  29. package/dist/cli/templates/vectors/openapi.js +2 -2
  30. package/dist/cli/templates/vectors/workflow.js +1 -1
  31. package/dist/cli/templates/vectors/workflow.js.map +1 -1
  32. package/dist/client/FusionClient.d.ts +55 -0
  33. package/dist/client/FusionClient.d.ts.map +1 -1
  34. package/dist/client/FusionClient.js +30 -0
  35. package/dist/client/FusionClient.js.map +1 -1
  36. package/dist/client/index.d.ts +1 -1
  37. package/dist/client/index.d.ts.map +1 -1
  38. package/dist/client/index.js.map +1 -1
  39. package/dist/core/builder/ActionGroupBuilder.d.ts +86 -46
  40. package/dist/core/builder/ActionGroupBuilder.d.ts.map +1 -1
  41. package/dist/core/builder/ActionGroupBuilder.js +68 -26
  42. package/dist/core/builder/ActionGroupBuilder.js.map +1 -1
  43. package/dist/core/builder/ErrorBuilder.d.ts +59 -0
  44. package/dist/core/builder/ErrorBuilder.d.ts.map +1 -0
  45. package/dist/core/builder/ErrorBuilder.js +99 -0
  46. package/dist/core/builder/ErrorBuilder.js.map +1 -0
  47. package/dist/core/builder/FluentRouter.d.ts +91 -0
  48. package/dist/core/builder/FluentRouter.d.ts.map +1 -0
  49. package/dist/core/builder/FluentRouter.js +121 -0
  50. package/dist/core/builder/FluentRouter.js.map +1 -0
  51. package/dist/core/builder/FluentSchemaHelpers.d.ts +237 -0
  52. package/dist/core/builder/FluentSchemaHelpers.d.ts.map +1 -0
  53. package/dist/core/builder/FluentSchemaHelpers.js +227 -0
  54. package/dist/core/builder/FluentSchemaHelpers.js.map +1 -0
  55. package/dist/core/builder/FluentToolBuilder.d.ts +347 -0
  56. package/dist/core/builder/FluentToolBuilder.d.ts.map +1 -0
  57. package/dist/core/builder/FluentToolBuilder.js +525 -0
  58. package/dist/core/builder/FluentToolBuilder.js.map +1 -0
  59. package/dist/core/builder/GroupedToolBuilder.d.ts +91 -1
  60. package/dist/core/builder/GroupedToolBuilder.d.ts.map +1 -1
  61. package/dist/core/builder/GroupedToolBuilder.js +122 -4
  62. package/dist/core/builder/GroupedToolBuilder.js.map +1 -1
  63. package/dist/core/builder/ToolDefinitionCompiler.d.ts +1 -0
  64. package/dist/core/builder/ToolDefinitionCompiler.d.ts.map +1 -1
  65. package/dist/core/builder/ToolDefinitionCompiler.js +1 -1
  66. package/dist/core/builder/ToolDefinitionCompiler.js.map +1 -1
  67. package/dist/core/builder/index.d.ts +4 -0
  68. package/dist/core/builder/index.d.ts.map +1 -1
  69. package/dist/core/builder/index.js +7 -0
  70. package/dist/core/builder/index.js.map +1 -1
  71. package/dist/core/execution/EgressGuard.js +1 -1
  72. package/dist/core/execution/EgressGuard.js.map +1 -1
  73. package/dist/core/execution/ExecutionPipeline.d.ts +8 -2
  74. package/dist/core/execution/ExecutionPipeline.d.ts.map +1 -1
  75. package/dist/core/execution/ExecutionPipeline.js +18 -9
  76. package/dist/core/execution/ExecutionPipeline.js.map +1 -1
  77. package/dist/core/execution/PipelineHooks.d.ts +0 -6
  78. package/dist/core/execution/PipelineHooks.d.ts.map +1 -1
  79. package/dist/core/execution/PipelineHooks.js +7 -3
  80. package/dist/core/execution/PipelineHooks.js.map +1 -1
  81. package/dist/core/index.d.ts +5 -7
  82. package/dist/core/index.d.ts.map +1 -1
  83. package/dist/core/index.js +2 -4
  84. package/dist/core/index.js.map +1 -1
  85. package/dist/core/initFusion.d.ts +119 -87
  86. package/dist/core/initFusion.d.ts.map +1 -1
  87. package/dist/core/initFusion.js +56 -66
  88. package/dist/core/initFusion.js.map +1 -1
  89. package/dist/core/registry/ToolRegistry.d.ts +1 -1
  90. package/dist/core/registry/ToolRegistry.d.ts.map +1 -1
  91. package/dist/core/registry/ToolRegistry.js +1 -1
  92. package/dist/core/registry/ToolRegistry.js.map +1 -1
  93. package/dist/core/schema/SchemaGenerator.d.ts +1 -1
  94. package/dist/core/schema/SchemaGenerator.d.ts.map +1 -1
  95. package/dist/core/schema/SchemaGenerator.js +38 -1
  96. package/dist/core/schema/SchemaGenerator.js.map +1 -1
  97. package/dist/core/types.d.ts +19 -0
  98. package/dist/core/types.d.ts.map +1 -1
  99. package/dist/exposition/ExpositionCompiler.d.ts.map +1 -1
  100. package/dist/exposition/ExpositionCompiler.js +25 -2
  101. package/dist/exposition/ExpositionCompiler.js.map +1 -1
  102. package/dist/index.d.ts +3 -3
  103. package/dist/index.d.ts.map +1 -1
  104. package/dist/index.js +4 -2
  105. package/dist/index.js.map +1 -1
  106. package/dist/introspection/BehaviorDigest.d.ts +2 -2
  107. package/dist/introspection/BehaviorDigest.d.ts.map +1 -1
  108. package/dist/introspection/BehaviorDigest.js +38 -36
  109. package/dist/introspection/BehaviorDigest.js.map +1 -1
  110. package/dist/introspection/CapabilityLockfile.d.ts +2 -2
  111. package/dist/introspection/CapabilityLockfile.d.ts.map +1 -1
  112. package/dist/introspection/CapabilityLockfile.js +9 -9
  113. package/dist/introspection/CapabilityLockfile.js.map +1 -1
  114. package/dist/introspection/CryptoAttestation.d.ts.map +1 -1
  115. package/dist/introspection/CryptoAttestation.js +27 -36
  116. package/dist/introspection/CryptoAttestation.js.map +1 -1
  117. package/dist/introspection/ToolContract.d.ts +2 -2
  118. package/dist/introspection/ToolContract.d.ts.map +1 -1
  119. package/dist/introspection/ToolContract.js +9 -9
  120. package/dist/introspection/ToolContract.js.map +1 -1
  121. package/dist/introspection/canonicalize.d.ts +16 -1
  122. package/dist/introspection/canonicalize.d.ts.map +1 -1
  123. package/dist/introspection/canonicalize.js +24 -3
  124. package/dist/introspection/canonicalize.js.map +1 -1
  125. package/dist/presenter/PostProcessor.d.ts +4 -2
  126. package/dist/presenter/PostProcessor.d.ts.map +1 -1
  127. package/dist/presenter/PostProcessor.js +10 -10
  128. package/dist/presenter/PostProcessor.js.map +1 -1
  129. package/dist/presenter/Presenter.d.ts +112 -6
  130. package/dist/presenter/Presenter.d.ts.map +1 -1
  131. package/dist/presenter/Presenter.js +134 -40
  132. package/dist/presenter/Presenter.js.map +1 -1
  133. package/dist/presenter/SelectUtils.d.ts +78 -0
  134. package/dist/presenter/SelectUtils.d.ts.map +1 -0
  135. package/dist/presenter/SelectUtils.js +141 -0
  136. package/dist/presenter/SelectUtils.js.map +1 -0
  137. package/dist/presenter/index.d.ts +3 -0
  138. package/dist/presenter/index.d.ts.map +1 -1
  139. package/dist/presenter/index.js +6 -0
  140. package/dist/presenter/index.js.map +1 -1
  141. package/dist/presenter/suggest.d.ts +39 -0
  142. package/dist/presenter/suggest.d.ts.map +1 -0
  143. package/dist/presenter/suggest.js +41 -0
  144. package/dist/presenter/suggest.js.map +1 -0
  145. package/dist/presenter/typeHelpers.d.ts +147 -0
  146. package/dist/presenter/typeHelpers.d.ts.map +1 -0
  147. package/dist/presenter/typeHelpers.js +152 -0
  148. package/dist/presenter/typeHelpers.js.map +1 -0
  149. package/dist/prompt/FluentPromptBuilder.d.ts +155 -0
  150. package/dist/prompt/FluentPromptBuilder.d.ts.map +1 -0
  151. package/dist/prompt/FluentPromptBuilder.js +193 -0
  152. package/dist/prompt/FluentPromptBuilder.js.map +1 -0
  153. package/dist/prompt/index.d.ts +1 -0
  154. package/dist/prompt/index.d.ts.map +1 -1
  155. package/dist/prompt/index.js +1 -0
  156. package/dist/prompt/index.js.map +1 -1
  157. package/dist/server/DevServer.js +8 -8
  158. package/dist/server/DevServer.js.map +1 -1
  159. package/dist/server/ServerAttachment.d.ts +1 -1
  160. package/dist/server/ServerAttachment.d.ts.map +1 -1
  161. package/dist/server/ServerAttachment.js +57 -4
  162. package/dist/server/ServerAttachment.js.map +1 -1
  163. package/dist/state-sync/ResponseDecorator.d.ts +1 -1
  164. package/dist/state-sync/StateSyncBuilder.d.ts +75 -0
  165. package/dist/state-sync/StateSyncBuilder.d.ts.map +1 -0
  166. package/dist/state-sync/StateSyncBuilder.js +123 -0
  167. package/dist/state-sync/StateSyncBuilder.js.map +1 -0
  168. package/dist/state-sync/index.d.ts +1 -0
  169. package/dist/state-sync/index.d.ts.map +1 -1
  170. package/dist/state-sync/index.js +1 -0
  171. package/dist/state-sync/index.js.map +1 -1
  172. package/package.json +1 -1
@@ -0,0 +1,347 @@
1
+ /**
2
+ * FluentToolBuilder — Type-Chaining Builder for Semantic Verb Tools
3
+ *
4
+ * The core builder behind `f.query()`, `f.mutation()`, and `f.action()`.
5
+ * Uses TypeScript generic accumulation so that each fluent step narrows
6
+ * the types — the IDE "magically" knows the exact shape of `input` and
7
+ * `ctx` inside `.handle()` without any manual Interface declaration.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * const f = initFusion<AppContext>();
12
+ *
13
+ * const listUsers = f.query('users.list')
14
+ * .describe('List users from the database')
15
+ * .withNumber('limit', 'Max results to return')
16
+ * .withOptionalEnum('status', ['active', 'inactive'], 'Filter by status')
17
+ * .returns(UserPresenter)
18
+ * .handle(async (input, ctx) => {
19
+ * return ctx.db.user.findMany({ take: input.limit });
20
+ * });
21
+ * ```
22
+ *
23
+ * @see {@link FluentRouter} for prefix grouping
24
+ * @see {@link initFusion} for the factory that creates these builders
25
+ *
26
+ * @module
27
+ */
28
+ import { type ZodType, type ZodObject, type ZodRawShape } from 'zod';
29
+ import { GroupedToolBuilder } from './GroupedToolBuilder.js';
30
+ import { type ToolResponse, type MiddlewareFn } from '../types.js';
31
+ import { type Presenter } from '../../presenter/Presenter.js';
32
+ import { type ConcurrencyConfig } from '../execution/ConcurrencyGuard.js';
33
+ /**
34
+ * Semantic defaults applied by each verb.
35
+ * @internal
36
+ */
37
+ export interface SemanticDefaults {
38
+ readonly readOnly?: boolean;
39
+ readonly destructive?: boolean;
40
+ readonly idempotent?: boolean;
41
+ }
42
+ /** Defaults for `f.query()` — read-only, no side effects */
43
+ export declare const QUERY_DEFAULTS: SemanticDefaults;
44
+ /** Defaults for `f.mutation()` — destructive, irreversible */
45
+ export declare const MUTATION_DEFAULTS: SemanticDefaults;
46
+ /** Defaults for `f.action()` — neutral, no assumptions */
47
+ export declare const ACTION_DEFAULTS: SemanticDefaults;
48
+ /**
49
+ * Fluent builder that accumulates types at each step.
50
+ *
51
+ * @typeParam TContext - Base application context (from `initFusion<TContext>()`)
52
+ * @typeParam TInput - Accumulated input type (built by `with*()` methods)
53
+ * @typeParam TCtx - Accumulated context type (enriched by `.use()`)
54
+ */
55
+ export declare class FluentToolBuilder<TContext, TInput = void, TCtx = TContext> {
56
+ /** @internal */ readonly _name: string;
57
+ /** @internal */ _description?: string;
58
+ /** @internal */ _instructions?: string;
59
+ /** @internal */ _inputSchema?: ZodObject<ZodRawShape>;
60
+ /** @internal */ _withParams: Record<string, ZodType>;
61
+ /** @internal */ _tags: string[];
62
+ /** @internal */ _middlewares: MiddlewareFn<TContext>[];
63
+ /** @internal */ _returns?: Presenter<unknown>;
64
+ /** @internal */ _semanticDefaults: SemanticDefaults;
65
+ /** @internal */ _readOnly?: boolean;
66
+ /** @internal */ _destructive?: boolean;
67
+ /** @internal */ _idempotent?: boolean;
68
+ /** @internal */ _toonMode: boolean;
69
+ /** @internal */ _annotations?: Record<string, unknown>;
70
+ /** @internal */ _invalidatesPatterns: string[];
71
+ /** @internal */ _cacheControl?: 'no-store' | 'immutable';
72
+ /** @internal */ _concurrency?: ConcurrencyConfig;
73
+ /** @internal */ _egressMaxBytes?: number;
74
+ /**
75
+ * @param name - Tool name in `domain.action` format (e.g. `'users.list'`)
76
+ * @param defaults - Semantic defaults from the verb (`query`, `mutation`, `action`)
77
+ */
78
+ constructor(name: string, defaults?: SemanticDefaults);
79
+ /**
80
+ * Set the tool description shown to the LLM.
81
+ *
82
+ * @param text - Human-readable description
83
+ * @returns `this` for chaining
84
+ */
85
+ describe(text: string): FluentToolBuilder<TContext, TInput, TCtx>;
86
+ /**
87
+ * Set AI-First instructions — injected as system-level guidance in the tool description.
88
+ *
89
+ * This is **Prompt Engineering embedded in the framework**. The instructions
90
+ * tell the LLM WHEN and HOW to use this tool, reducing hallucination.
91
+ *
92
+ * @param text - System prompt for the tool
93
+ * @returns `this` for chaining
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * f.query('docs.search')
98
+ * .describe('Search internal documentation')
99
+ * .instructions('Use ONLY when the user asks about internal policies.')
100
+ * .withString('query', 'Search term')
101
+ * .handle(async (input) => { ... });
102
+ * ```
103
+ */
104
+ instructions(text: string): FluentToolBuilder<TContext, TInput, TCtx>;
105
+ /**
106
+ * Add a required string parameter.
107
+ *
108
+ * @param name - Parameter name
109
+ * @param description - Human-readable description for the LLM
110
+ * @returns Builder with narrowed `TInput` type
111
+ *
112
+ * @example
113
+ * ```typescript
114
+ * f.query('projects.get')
115
+ * .withString('project_id', 'The project ID to retrieve')
116
+ * .handle(async (input) => { ... });
117
+ * // input.project_id: string ✅
118
+ * ```
119
+ */
120
+ withString<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Record<K, string>, TCtx>;
121
+ /**
122
+ * Add an optional string parameter.
123
+ *
124
+ * @param name - Parameter name
125
+ * @param description - Human-readable description for the LLM
126
+ * @returns Builder with narrowed `TInput` type
127
+ */
128
+ withOptionalString<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Partial<Record<K, string>>, TCtx>;
129
+ /**
130
+ * Add a required number parameter.
131
+ *
132
+ * @param name - Parameter name
133
+ * @param description - Human-readable description for the LLM
134
+ * @returns Builder with narrowed `TInput` type
135
+ */
136
+ withNumber<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Record<K, number>, TCtx>;
137
+ /**
138
+ * Add an optional number parameter.
139
+ *
140
+ * @param name - Parameter name
141
+ * @param description - Human-readable description for the LLM
142
+ * @returns Builder with narrowed `TInput` type
143
+ */
144
+ withOptionalNumber<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Partial<Record<K, number>>, TCtx>;
145
+ /**
146
+ * Add a required boolean parameter.
147
+ *
148
+ * @param name - Parameter name
149
+ * @param description - Human-readable description for the LLM
150
+ * @returns Builder with narrowed `TInput` type
151
+ */
152
+ withBoolean<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Record<K, boolean>, TCtx>;
153
+ /**
154
+ * Add an optional boolean parameter.
155
+ *
156
+ * @param name - Parameter name
157
+ * @param description - Human-readable description for the LLM
158
+ * @returns Builder with narrowed `TInput` type
159
+ */
160
+ withOptionalBoolean<K extends string>(name: K, description?: string): FluentToolBuilder<TContext, TInput & Partial<Record<K, boolean>>, TCtx>;
161
+ /**
162
+ * Add a required enum parameter.
163
+ *
164
+ * @param name - Parameter name
165
+ * @param values - Allowed enum values
166
+ * @param description - Human-readable description for the LLM
167
+ * @returns Builder with narrowed `TInput` type
168
+ *
169
+ * @example
170
+ * ```typescript
171
+ * f.query('invoices.list')
172
+ * .withEnum('status', ['draft', 'sent', 'paid'], 'Filter by status')
173
+ * .handle(async (input) => { ... });
174
+ * // input.status: 'draft' | 'sent' | 'paid' ✅
175
+ * ```
176
+ */
177
+ withEnum<K extends string, V extends string>(name: K, values: readonly [V, ...V[]], description?: string): FluentToolBuilder<TContext, TInput & Record<K, V>, TCtx>;
178
+ /**
179
+ * Add an optional enum parameter.
180
+ *
181
+ * @param name - Parameter name
182
+ * @param values - Allowed enum values
183
+ * @param description - Human-readable description for the LLM
184
+ * @returns Builder with narrowed `TInput` type
185
+ */
186
+ withOptionalEnum<K extends string, V extends string>(name: K, values: readonly [V, ...V[]], description?: string): FluentToolBuilder<TContext, TInput & Partial<Record<K, V>>, TCtx>;
187
+ /**
188
+ * Add a required array parameter.
189
+ *
190
+ * @param name - Parameter name
191
+ * @param itemType - Type of array items (`'string'`, `'number'`, `'boolean'`)
192
+ * @param description - Human-readable description for the LLM
193
+ * @returns Builder with narrowed `TInput` type
194
+ *
195
+ * @example
196
+ * ```typescript
197
+ * f.mutation('tasks.tag')
198
+ * .withString('task_id', 'The task to tag')
199
+ * .withArray('tags', 'string', 'Tags to apply')
200
+ * .handle(async (input) => { ... });
201
+ * // input.tags: string[] ✅
202
+ * ```
203
+ */
204
+ withArray<K extends string, I extends 'string' | 'number' | 'boolean'>(name: K, itemType: I, description?: string): FluentToolBuilder<TContext, TInput & Record<K, (I extends 'string' ? string : I extends 'number' ? number : boolean)[]>, TCtx>;
205
+ /**
206
+ * Add an optional array parameter.
207
+ *
208
+ * @param name - Parameter name
209
+ * @param itemType - Type of array items (`'string'`, `'number'`, `'boolean'`)
210
+ * @param description - Human-readable description for the LLM
211
+ * @returns Builder with narrowed `TInput` type
212
+ */
213
+ withOptionalArray<K extends string, I extends 'string' | 'number' | 'boolean'>(name: K, itemType: I, description?: string): FluentToolBuilder<TContext, TInput & Partial<Record<K, (I extends 'string' ? string : I extends 'number' ? number : boolean)[]>>, TCtx>;
214
+ /**
215
+ * Add context-derivation middleware (tRPC-style).
216
+ *
217
+ * The middleware receives `{ ctx, next }` and can enrich the context
218
+ * for downstream steps. The TypeScript type of `ctx` in `.handle()`
219
+ * is automatically extended with the derived properties.
220
+ *
221
+ * @param mw - Middleware that returns enriched context
222
+ * @returns A **new type** of `FluentToolBuilder` with `TCtx` enriched
223
+ *
224
+ * @example
225
+ * ```typescript
226
+ * f.mutation('users.delete')
227
+ * .use(async ({ ctx, next }) => {
228
+ * const admin = await requireAdmin(ctx.headers);
229
+ * return next({ ...ctx, adminUser: admin });
230
+ * })
231
+ * .withString('id', 'User ID to delete')
232
+ * .handle(async (input, ctx) => {
233
+ * // ctx.adminUser is typed! Zero casting.
234
+ * ctx.logger.info(`${ctx.adminUser.name} deleting ${input.id}`);
235
+ * });
236
+ * ```
237
+ */
238
+ use<TDerived extends Record<string, unknown>>(mw: (args: {
239
+ ctx: TCtx;
240
+ next: (enrichedCtx: TCtx & TDerived) => Promise<ToolResponse>;
241
+ }) => Promise<ToolResponse>): FluentToolBuilder<TContext, TInput, TCtx & TDerived>;
242
+ /**
243
+ * Set the MVA Presenter for automatic response formatting.
244
+ *
245
+ * When a Presenter is attached, the handler can return raw data
246
+ * and the framework pipes it through schema validation, system rules,
247
+ * and UI block generation.
248
+ *
249
+ * @param presenter - A Presenter instance
250
+ * @returns `this` for chaining
251
+ */
252
+ returns(presenter: Presenter<unknown>): FluentToolBuilder<TContext, TInput, TCtx>;
253
+ /**
254
+ * Add capability tags for selective tool exposure.
255
+ *
256
+ * Tags are accumulated — calling `.tags()` multiple times
257
+ * (or inheriting from a router) appends rather than replaces.
258
+ *
259
+ * @param tags - Tag strings for filtering
260
+ * @returns `this` for chaining
261
+ */
262
+ tags(...tags: string[]): FluentToolBuilder<TContext, TInput, TCtx>;
263
+ /** Override: mark this tool as read-only (no side effects) */
264
+ readOnly(): FluentToolBuilder<TContext, TInput, TCtx>;
265
+ /** Override: mark this tool as destructive (irreversible) */
266
+ destructive(): FluentToolBuilder<TContext, TInput, TCtx>;
267
+ /** Override: mark this tool as idempotent (safe to retry) */
268
+ idempotent(): FluentToolBuilder<TContext, TInput, TCtx>;
269
+ /**
270
+ * Enable TOON-formatted descriptions for token optimization.
271
+ *
272
+ * @returns `this` for chaining
273
+ */
274
+ toonDescription(): FluentToolBuilder<TContext, TInput, TCtx>;
275
+ /**
276
+ * Set MCP tool annotations.
277
+ *
278
+ * @param a - Annotation key-value pairs
279
+ * @returns `this` for chaining
280
+ */
281
+ annotations(a: Record<string, unknown>): FluentToolBuilder<TContext, TInput, TCtx>;
282
+ /**
283
+ * Declare glob patterns invalidated when this tool succeeds.
284
+ *
285
+ * @param patterns - Glob patterns (e.g. `'sprints.*'`, `'tasks.*'`)
286
+ * @returns `this` for chaining
287
+ */
288
+ invalidates(...patterns: string[]): FluentToolBuilder<TContext, TInput, TCtx>;
289
+ /**
290
+ * Mark this tool's data as immutable (safe to cache forever).
291
+ *
292
+ * @returns `this` for chaining
293
+ */
294
+ cached(): FluentToolBuilder<TContext, TInput, TCtx>;
295
+ /**
296
+ * Mark this tool's data as volatile (never cache).
297
+ *
298
+ * @returns `this` for chaining
299
+ */
300
+ stale(): FluentToolBuilder<TContext, TInput, TCtx>;
301
+ /**
302
+ * Set concurrency limits for this tool (Semaphore + Queue pattern).
303
+ *
304
+ * @param config - Concurrency configuration
305
+ * @returns `this` for chaining
306
+ */
307
+ concurrency(config: ConcurrencyConfig): FluentToolBuilder<TContext, TInput, TCtx>;
308
+ /**
309
+ * Set maximum payload size for tool responses (Egress Guard).
310
+ *
311
+ * @param bytes - Maximum payload size in bytes
312
+ * @returns `this` for chaining
313
+ */
314
+ egress(bytes: number): FluentToolBuilder<TContext, TInput, TCtx>;
315
+ /**
316
+ * Set the handler and build the tool — the terminal step.
317
+ *
318
+ * The handler receives `(input, ctx)` with fully typed `TInput` and `TCtx`.
319
+ * **Implicit `success()` wrapping**: if the handler returns raw data
320
+ * (not a `ToolResponse`), the framework wraps it with `success()`.
321
+ *
322
+ * @param handler - Async function receiving typed `(input, ctx)`
323
+ * @returns A `GroupedToolBuilder` ready for registration
324
+ *
325
+ * @example
326
+ * ```typescript
327
+ * const getProject = f.query('projects.get')
328
+ * .describe('Get a project by ID')
329
+ * .withString('project_id', 'The exact project ID')
330
+ * .handle(async (input, ctx) => {
331
+ * return await ctx.db.projects.findUnique({ where: { id: input.project_id } });
332
+ * });
333
+ * ```
334
+ */
335
+ handle(handler: (input: TInput extends void ? Record<string, unknown> : TInput, ctx: TCtx) => Promise<ToolResponse | unknown>): GroupedToolBuilder<TContext>;
336
+ /**
337
+ * Alias for `.handle()` — for backward compatibility.
338
+ * @internal
339
+ */
340
+ resolve(handler: (args: {
341
+ input: TInput extends void ? Record<string, unknown> : TInput;
342
+ ctx: TCtx;
343
+ }) => Promise<ToolResponse | unknown>): GroupedToolBuilder<TContext>;
344
+ /** @internal */
345
+ private _build;
346
+ }
347
+ //# sourceMappingURL=FluentToolBuilder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"FluentToolBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/FluentToolBuilder.ts"],"names":[],"mappings":"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"}