@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.
- package/dist/cli/fusion.d.ts +3 -0
- package/dist/cli/fusion.d.ts.map +1 -1
- package/dist/cli/fusion.js +125 -3
- package/dist/cli/fusion.js.map +1 -1
- package/dist/cli/templates/config.js +3 -3
- package/dist/cli/templates/config.js.map +1 -1
- package/dist/cli/templates/constants.d.ts +1 -1
- package/dist/cli/templates/constants.d.ts.map +1 -1
- package/dist/cli/templates/constants.js +1 -1
- package/dist/cli/templates/constants.js.map +1 -1
- package/dist/cli/templates/core.js +5 -5
- package/dist/cli/templates/middleware.d.ts +1 -1
- package/dist/cli/templates/middleware.d.ts.map +1 -1
- package/dist/cli/templates/middleware.js +16 -13
- package/dist/cli/templates/middleware.js.map +1 -1
- package/dist/cli/templates/readme.d.ts.map +1 -1
- package/dist/cli/templates/readme.js +14 -18
- package/dist/cli/templates/readme.js.map +1 -1
- package/dist/cli/templates/tools.d.ts +4 -0
- package/dist/cli/templates/tools.d.ts.map +1 -1
- package/dist/cli/templates/tools.js +26 -29
- package/dist/cli/templates/tools.js.map +1 -1
- package/dist/cli/templates/vectors/database.d.ts.map +1 -1
- package/dist/cli/templates/vectors/database.js +14 -19
- package/dist/cli/templates/vectors/database.js.map +1 -1
- package/dist/cli/templates/vectors/oauth.d.ts.map +1 -1
- package/dist/cli/templates/vectors/oauth.js +4 -5
- package/dist/cli/templates/vectors/oauth.js.map +1 -1
- package/dist/cli/templates/vectors/openapi.js +2 -2
- package/dist/cli/templates/vectors/workflow.js +1 -1
- package/dist/cli/templates/vectors/workflow.js.map +1 -1
- package/dist/client/FusionClient.d.ts +55 -0
- package/dist/client/FusionClient.d.ts.map +1 -1
- package/dist/client/FusionClient.js +30 -0
- package/dist/client/FusionClient.js.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/core/builder/ActionGroupBuilder.d.ts +86 -46
- package/dist/core/builder/ActionGroupBuilder.d.ts.map +1 -1
- package/dist/core/builder/ActionGroupBuilder.js +68 -26
- package/dist/core/builder/ActionGroupBuilder.js.map +1 -1
- package/dist/core/builder/ErrorBuilder.d.ts +59 -0
- package/dist/core/builder/ErrorBuilder.d.ts.map +1 -0
- package/dist/core/builder/ErrorBuilder.js +99 -0
- package/dist/core/builder/ErrorBuilder.js.map +1 -0
- package/dist/core/builder/FluentRouter.d.ts +91 -0
- package/dist/core/builder/FluentRouter.d.ts.map +1 -0
- package/dist/core/builder/FluentRouter.js +121 -0
- package/dist/core/builder/FluentRouter.js.map +1 -0
- package/dist/core/builder/FluentSchemaHelpers.d.ts +237 -0
- package/dist/core/builder/FluentSchemaHelpers.d.ts.map +1 -0
- package/dist/core/builder/FluentSchemaHelpers.js +227 -0
- package/dist/core/builder/FluentSchemaHelpers.js.map +1 -0
- package/dist/core/builder/FluentToolBuilder.d.ts +347 -0
- package/dist/core/builder/FluentToolBuilder.d.ts.map +1 -0
- package/dist/core/builder/FluentToolBuilder.js +525 -0
- package/dist/core/builder/FluentToolBuilder.js.map +1 -0
- package/dist/core/builder/GroupedToolBuilder.d.ts +91 -1
- package/dist/core/builder/GroupedToolBuilder.d.ts.map +1 -1
- package/dist/core/builder/GroupedToolBuilder.js +122 -4
- package/dist/core/builder/GroupedToolBuilder.js.map +1 -1
- package/dist/core/builder/ToolDefinitionCompiler.d.ts +1 -0
- package/dist/core/builder/ToolDefinitionCompiler.d.ts.map +1 -1
- package/dist/core/builder/ToolDefinitionCompiler.js +1 -1
- package/dist/core/builder/ToolDefinitionCompiler.js.map +1 -1
- package/dist/core/builder/index.d.ts +4 -0
- package/dist/core/builder/index.d.ts.map +1 -1
- package/dist/core/builder/index.js +7 -0
- package/dist/core/builder/index.js.map +1 -1
- package/dist/core/execution/EgressGuard.js +1 -1
- package/dist/core/execution/EgressGuard.js.map +1 -1
- package/dist/core/execution/ExecutionPipeline.d.ts +8 -2
- package/dist/core/execution/ExecutionPipeline.d.ts.map +1 -1
- package/dist/core/execution/ExecutionPipeline.js +18 -9
- package/dist/core/execution/ExecutionPipeline.js.map +1 -1
- package/dist/core/execution/PipelineHooks.d.ts +0 -6
- package/dist/core/execution/PipelineHooks.d.ts.map +1 -1
- package/dist/core/execution/PipelineHooks.js +7 -3
- package/dist/core/execution/PipelineHooks.js.map +1 -1
- package/dist/core/index.d.ts +5 -7
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +2 -4
- package/dist/core/index.js.map +1 -1
- package/dist/core/initFusion.d.ts +119 -87
- package/dist/core/initFusion.d.ts.map +1 -1
- package/dist/core/initFusion.js +56 -66
- package/dist/core/initFusion.js.map +1 -1
- package/dist/core/registry/ToolRegistry.d.ts +1 -1
- package/dist/core/registry/ToolRegistry.d.ts.map +1 -1
- package/dist/core/registry/ToolRegistry.js +1 -1
- package/dist/core/registry/ToolRegistry.js.map +1 -1
- package/dist/core/schema/SchemaGenerator.d.ts +1 -1
- package/dist/core/schema/SchemaGenerator.d.ts.map +1 -1
- package/dist/core/schema/SchemaGenerator.js +38 -1
- package/dist/core/schema/SchemaGenerator.js.map +1 -1
- package/dist/core/types.d.ts +19 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/exposition/ExpositionCompiler.d.ts.map +1 -1
- package/dist/exposition/ExpositionCompiler.js +25 -2
- package/dist/exposition/ExpositionCompiler.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -2
- package/dist/index.js.map +1 -1
- package/dist/introspection/BehaviorDigest.d.ts +2 -2
- package/dist/introspection/BehaviorDigest.d.ts.map +1 -1
- package/dist/introspection/BehaviorDigest.js +38 -36
- package/dist/introspection/BehaviorDigest.js.map +1 -1
- package/dist/introspection/CapabilityLockfile.d.ts +2 -2
- package/dist/introspection/CapabilityLockfile.d.ts.map +1 -1
- package/dist/introspection/CapabilityLockfile.js +9 -9
- package/dist/introspection/CapabilityLockfile.js.map +1 -1
- package/dist/introspection/CryptoAttestation.d.ts.map +1 -1
- package/dist/introspection/CryptoAttestation.js +27 -36
- package/dist/introspection/CryptoAttestation.js.map +1 -1
- package/dist/introspection/ToolContract.d.ts +2 -2
- package/dist/introspection/ToolContract.d.ts.map +1 -1
- package/dist/introspection/ToolContract.js +9 -9
- package/dist/introspection/ToolContract.js.map +1 -1
- package/dist/introspection/canonicalize.d.ts +16 -1
- package/dist/introspection/canonicalize.d.ts.map +1 -1
- package/dist/introspection/canonicalize.js +24 -3
- package/dist/introspection/canonicalize.js.map +1 -1
- package/dist/presenter/PostProcessor.d.ts +4 -2
- package/dist/presenter/PostProcessor.d.ts.map +1 -1
- package/dist/presenter/PostProcessor.js +10 -10
- package/dist/presenter/PostProcessor.js.map +1 -1
- package/dist/presenter/Presenter.d.ts +112 -6
- package/dist/presenter/Presenter.d.ts.map +1 -1
- package/dist/presenter/Presenter.js +134 -40
- package/dist/presenter/Presenter.js.map +1 -1
- package/dist/presenter/SelectUtils.d.ts +78 -0
- package/dist/presenter/SelectUtils.d.ts.map +1 -0
- package/dist/presenter/SelectUtils.js +141 -0
- package/dist/presenter/SelectUtils.js.map +1 -0
- package/dist/presenter/index.d.ts +3 -0
- package/dist/presenter/index.d.ts.map +1 -1
- package/dist/presenter/index.js +6 -0
- package/dist/presenter/index.js.map +1 -1
- package/dist/presenter/suggest.d.ts +39 -0
- package/dist/presenter/suggest.d.ts.map +1 -0
- package/dist/presenter/suggest.js +41 -0
- package/dist/presenter/suggest.js.map +1 -0
- package/dist/presenter/typeHelpers.d.ts +147 -0
- package/dist/presenter/typeHelpers.d.ts.map +1 -0
- package/dist/presenter/typeHelpers.js +152 -0
- package/dist/presenter/typeHelpers.js.map +1 -0
- package/dist/prompt/FluentPromptBuilder.d.ts +155 -0
- package/dist/prompt/FluentPromptBuilder.d.ts.map +1 -0
- package/dist/prompt/FluentPromptBuilder.js +193 -0
- package/dist/prompt/FluentPromptBuilder.js.map +1 -0
- package/dist/prompt/index.d.ts +1 -0
- package/dist/prompt/index.d.ts.map +1 -1
- package/dist/prompt/index.js +1 -0
- package/dist/prompt/index.js.map +1 -1
- package/dist/server/DevServer.js +8 -8
- package/dist/server/DevServer.js.map +1 -1
- package/dist/server/ServerAttachment.d.ts +1 -1
- package/dist/server/ServerAttachment.d.ts.map +1 -1
- package/dist/server/ServerAttachment.js +57 -4
- package/dist/server/ServerAttachment.js.map +1 -1
- package/dist/state-sync/ResponseDecorator.d.ts +1 -1
- package/dist/state-sync/StateSyncBuilder.d.ts +75 -0
- package/dist/state-sync/StateSyncBuilder.d.ts.map +1 -0
- package/dist/state-sync/StateSyncBuilder.js +123 -0
- package/dist/state-sync/StateSyncBuilder.js.map +1 -0
- package/dist/state-sync/index.d.ts +1 -0
- package/dist/state-sync/index.d.ts.map +1 -1
- package/dist/state-sync/index.js +1 -0
- package/dist/state-sync/index.js.map +1 -1
- 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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"}
|