@vurb/core 3.2.0

package/dist/core/builder/ActionGroupBuilder.d.ts

@@ -0,0 +1,208 @@
+/**
+ * ActionGroupBuilder — Sub-builder for Hierarchical Action Groups
+ *
+ * Used within {@link GroupedToolBuilder.group} callbacks to register
+ * actions under a named group. Supports group-scoped middleware and
+ * generates compound keys (e.g., `"users.create"`).
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TCommon - Common schema shape (inferred from parent builder)
+ *
+ * @example
+ * ```typescript
+ * createTool<AppContext>('platform')
+ *     .group('users', 'User management', g => g
+ *         .use(requireAdmin)
+ *         .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+ *         .mutation('ban', async (ctx, args) => {
+ *             await ctx.db.users.ban(args.user_id);
+ *             return success('User banned');
+ *         })
+ *     );
+ * ```
+ *
+ * @see {@link GroupedToolBuilder.group} for creating groups
+ * @see {@link MiddlewareFn} for middleware signature
+ *
+ * @module
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type ToolResponse, type InternalAction, type MiddlewareFn, type ActionConfig } from '../types.js';
+import { type MiddlewareDefinition } from '../middleware/ContextDerivation.js';
+/**
+ * Callback for configuring actions within a group.
+ *
+ * Receives an {@link ActionGroupBuilder} to register actions and middleware.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TCommon - Common schema shape
+ *
+ * @example
+ * ```typescript
+ * const configure: GroupConfigurator<AppContext, { workspace_id: string }> = (g) => g
+ *     .query('list', listHandler)
+ *     .mutation('delete', deleteHandler);
+ *
+ * builder.group('users', 'User management', configure);
+ * ```
+ */
+export type GroupConfigurator<TContext, TCommon extends Record<string, unknown>> = (group: ActionGroupBuilder<TContext, TCommon>) => void;
+/**
+ * Map `ActionConfig` properties to `InternalAction` base fields.
+ *
+ * Both `GroupedToolBuilder.action()` and `ActionGroupBuilder.action()`
+ * perform this same mapping. Extracted here to eliminate duplication
+ * and ensure a single source of truth.
+ *
+ * @param config - The action configuration from the public API
+ * @param omitCommonFields - Resolved omitCommon fields (already merged/deduped)
+ * @returns Base fields for building an `InternalAction`
+ *
+ * @internal
+ */
+export declare function mapConfigToActionFields<TContext>(config: ActionConfig<TContext>, omitCommonFields: string[] | undefined): Pick<InternalAction<TContext>, 'actionName' | 'description' | 'schema' | 'destructive' | 'idempotent' | 'readOnly' | 'handler' | 'omitCommonFields' | 'returns'>;
+/**
+ * Handler function type for semantic verb shortcuts.
+ * @typeParam TContext - Application context type
+ */
+type ActionHandler<TContext> = (ctx: TContext, args: Record<string, unknown>) => Promise<ToolResponse>;
+export declare class ActionGroupBuilder<TContext, TCommon extends Record<string, unknown> = Record<string, never>> {
+    /** @internal */
+    readonly _actions: InternalAction<TContext>[];
+    private readonly _groupName;
+    private readonly _groupDescription;
+    private readonly _groupMiddlewares;
+    private _groupOmitCommon;
+    constructor(groupName: string, description?: string);
+    /**
+     * Add middleware scoped to this group only.
+     *
+     * Unlike {@link GroupedToolBuilder.use}, this middleware runs
+     * only for actions within this group — not globally.
+     *
+     * Accepts both `MiddlewareDefinition` from `f.middleware()` and
+     * raw `MiddlewareFn` functions.
+     *
+     * @param mw - Middleware function or MiddlewareDefinition
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('admin', 'Admin operations', (g) => g
+     *     .use(requireAdmin)
+     *     .query('list', listHandler)
+     *     .mutation('reset', resetHandler)
+     * );
+     * ```
+     *
+     * @see {@link MiddlewareFn} for the middleware signature
+     */
+    use(mw: MiddlewareFn<TContext> | MiddlewareDefinition<TContext, Record<string, unknown>>): this;
+    /**
+     * Omit common schema fields for all actions in this group.
+     *
+     * Use when an entire group derives common fields from context
+     * (e.g. a "profile" group that resolves `workspace_id` from the JWT).
+     *
+     * Per-action `omitCommon` merges with group-level omissions.
+     *
+     * @param fields - Common field names to omit
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('profile', 'User profile', (g) => g
+     *     .omitCommon('workspace_id')
+     *     .query('me', meHandler)
+     * );
+     * ```
+     */
+    omitCommon(...fields: string[]): this;
+    /**
+     * Register a **read-only** action (readOnly: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * The action name is automatically prefixed with the group name
+     * (e.g., `"list"` in group `"users"` → `"users.list"`).
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+     *     .query('get', async (ctx, args) => success(await ctx.db.users.find(args.id)))
+     * );
+     * ```
+     */
+    query(name: string, handler: ActionHandler<TContext>): this;
+    /**
+     * Register a **destructive** action (destructive: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * Signals to the LLM that this action has irreversible side effects.
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .mutation('ban', async (ctx, args) => {
+     *         await ctx.db.users.ban(args.user_id);
+     *         return success('User banned');
+     *     })
+     * );
+     * ```
+     */
+    mutation(name: string, handler: ActionHandler<TContext>): this;
+    /**
+     * Register an action within this group.
+     *
+     * **As a 2-arg shortcut** `action(name, handler)`: registers a standard
+     * action (neither read-only nor destructive). This completes the
+     * semantic verb trio alongside `.query()` and `.mutation()`.
+     *
+     * **As a config object** `action({ name, schema, ... })`: full control
+     * over all action properties (schema, description, omitCommon, etc.).
+     *
+     * The action key is automatically prefixed with the group name
+     * (e.g., action `"create"` in group `"users"` becomes `"users.create"`).
+     *
+     * @param config - Action configuration OR action name (string)
+     * @param handler - Handler function (only when first arg is a string)
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .query('list', listHandler)
+     *     .action('invite', inviteHandler)
+     *     .mutation('ban', banHandler)
+     * );
+     * ```
+     *
+     * @see {@link ActionGroupBuilder.query} — read-only actions
+     * @see {@link ActionGroupBuilder.mutation} — destructive actions
+     * @see {@link ActionConfig} for all configuration options
+     */
+    action<TSchema extends ZodObject<ZodRawShape>, TOmit extends keyof TCommon = never>(config: {
+        name: string;
+        description?: string;
+        schema: TSchema;
+        destructive?: boolean;
+        idempotent?: boolean;
+        readOnly?: boolean;
+        omitCommon?: TOmit[];
+        handler: (ctx: TContext, args: TSchema["_output"] & Omit<TCommon, TOmit>) => Promise<ToolResponse>;
+    }): this;
+    /** Register a standard action (2-arg shorthand: neither readOnly nor destructive) */
+    action(name: string, handler: ActionHandler<TContext>): this;
+    /** Register an action within this group (config object) */
+    action(config: ActionConfig<TContext>): this;
+}
+export {};
+//# sourceMappingURL=ActionGroupBuilder.d.ts.map

package/dist/core/builder/ActionGroupBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionGroupBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"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"}

package/dist/core/builder/ActionGroupBuilder.js

@@ -0,0 +1,193 @@
+/**
+ * ActionGroupBuilder — Sub-builder for Hierarchical Action Groups
+ *
+ * Used within {@link GroupedToolBuilder.group} callbacks to register
+ * actions under a named group. Supports group-scoped middleware and
+ * generates compound keys (e.g., `"users.create"`).
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TCommon - Common schema shape (inferred from parent builder)
+ *
+ * @example
+ * ```typescript
+ * createTool<AppContext>('platform')
+ *     .group('users', 'User management', g => g
+ *         .use(requireAdmin)
+ *         .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+ *         .mutation('ban', async (ctx, args) => {
+ *             await ctx.db.users.ban(args.user_id);
+ *             return success('User banned');
+ *         })
+ *     );
+ * ```
+ *
+ * @see {@link GroupedToolBuilder.group} for creating groups
+ * @see {@link MiddlewareFn} for middleware signature
+ *
+ * @module
+ */
+import {} from 'zod';
+import {} from '../types.js';
+import { resolveMiddleware } from '../middleware/ContextDerivation.js';
+// ── Shared Config → InternalAction Mapper ────────────────
+/**
+ * Map `ActionConfig` properties to `InternalAction` base fields.
+ *
+ * Both `GroupedToolBuilder.action()` and `ActionGroupBuilder.action()`
+ * perform this same mapping. Extracted here to eliminate duplication
+ * and ensure a single source of truth.
+ *
+ * @param config - The action configuration from the public API
+ * @param omitCommonFields - Resolved omitCommon fields (already merged/deduped)
+ * @returns Base fields for building an `InternalAction`
+ *
+ * @internal
+ */
+export function mapConfigToActionFields(config, omitCommonFields) {
+    return {
+        actionName: config.name,
+        description: config.description ?? undefined,
+        schema: config.schema ?? undefined,
+        destructive: config.destructive ?? undefined,
+        idempotent: config.idempotent ?? undefined,
+        readOnly: config.readOnly ?? undefined,
+        handler: config.handler,
+        omitCommonFields: (omitCommonFields?.length ?? 0) > 0 ? omitCommonFields : undefined,
+        returns: config.returns ?? undefined,
+    };
+}
+// ── ActionGroupBuilder ───────────────────────────────────
+export class ActionGroupBuilder {
+    /** @internal */
+    _actions = [];
+    _groupName;
+    _groupDescription;
+    _groupMiddlewares = [];
+    _groupOmitCommon = [];
+    constructor(groupName, description) {
+        this._groupName = groupName;
+        this._groupDescription = description || '';
+    }
+    /**
+     * Add middleware scoped to this group only.
+     *
+     * Unlike {@link GroupedToolBuilder.use}, this middleware runs
+     * only for actions within this group — not globally.
+     *
+     * Accepts both `MiddlewareDefinition` from `f.middleware()` and
+     * raw `MiddlewareFn` functions.
+     *
+     * @param mw - Middleware function or MiddlewareDefinition
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('admin', 'Admin operations', (g) => g
+     *     .use(requireAdmin)
+     *     .query('list', listHandler)
+     *     .mutation('reset', resetHandler)
+     * );
+     * ```
+     *
+     * @see {@link MiddlewareFn} for the middleware signature
+     */
+    use(mw) {
+        this._groupMiddlewares.push(resolveMiddleware(mw));
+        return this;
+    }
+    /**
+     * Omit common schema fields for all actions in this group.
+     *
+     * Use when an entire group derives common fields from context
+     * (e.g. a "profile" group that resolves `workspace_id` from the JWT).
+     *
+     * Per-action `omitCommon` merges with group-level omissions.
+     *
+     * @param fields - Common field names to omit
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('profile', 'User profile', (g) => g
+     *     .omitCommon('workspace_id')
+     *     .query('me', meHandler)
+     * );
+     * ```
+     */
+    omitCommon(...fields) {
+        this._groupOmitCommon.push(...fields);
+        return this;
+    }
+    // ── Semantic Verb Shortcuts ──────────────────────────
+    /**
+     * Register a **read-only** action (readOnly: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * The action name is automatically prefixed with the group name
+     * (e.g., `"list"` in group `"users"` → `"users.list"`).
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+     *     .query('get', async (ctx, args) => success(await ctx.db.users.find(args.id)))
+     * );
+     * ```
+     */
+    query(name, handler) {
+        return this.action({ name, readOnly: true, handler });
+    }
+    /**
+     * Register a **destructive** action (destructive: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * Signals to the LLM that this action has irreversible side effects.
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .mutation('ban', async (ctx, args) => {
+     *         await ctx.db.users.ban(args.user_id);
+     *         return success('User banned');
+     *     })
+     * );
+     * ```
+     */
+    mutation(name, handler) {
+        return this.action({ name, destructive: true, handler });
+    }
+    action(configOrName, maybeHandler) {
+        // 2-arg shorthand: action('invite', inviteHandler)
+        if (typeof configOrName === 'string' && typeof maybeHandler !== 'function') {
+            throw new Error(`action("${configOrName}") requires a handler function as the second argument.`);
+        }
+        const config = typeof configOrName === 'string'
+            ? { name: configOrName, handler: maybeHandler }
+            : configOrName;
+        if (config.name.includes('.')) {
+            throw new Error(`Action name "${config.name}" must not contain dots. ` +
+                `The framework uses dots internally for group.action compound keys.`);
+        }
+        // Merge group-level + per-action omissions (deduped)
+        const perAction = config.omitCommon ?? [];
+        const mergedOmit = [...new Set([...this._groupOmitCommon, ...perAction])];
+        this._actions.push({
+            key: `${this._groupName}.${config.name}`,
+            groupName: this._groupName,
+            groupDescription: this._groupDescription,
+            ...mapConfigToActionFields(config, mergedOmit),
+            middlewares: this._groupMiddlewares.length > 0
+                ? [...this._groupMiddlewares] : undefined,
+        });
+        return this;
+    }
+}
+//# sourceMappingURL=ActionGroupBuilder.js.map

package/dist/core/builder/ActionGroupBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionGroupBuilder.js","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"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"}

package/dist/core/builder/ErrorBuilder.d.ts

@@ -0,0 +1,59 @@
+import type { ErrorCode, ErrorSeverity, ToolResponse } from '../response.js';
+/**
+ * ErrorBuilder — Fluent API for Self-Healing Errors
+ *
+ * Provides a chaining interface to construct structured tool errors
+ * with recovery suggestions, available actions, and metadata.
+ *
+ * Designed to be used via `f.error()` in a tool handler.
+ *
+ * @example
+ * ```typescript
+ * return f.error('NOT_FOUND', `Project "${id}" missing`)
+ *     .suggest('Check the ID and try again')
+ *     .actions('projects.list')
+ *     .critical();
+ * ```
+ */
+export declare class ErrorBuilder {
+    private _message;
+    private _code;
+    private _suggestion?;
+    private _actions;
+    private _severity;
+    private _details;
+    private _retryAfter?;
+    /** @internal Cached build result — invalidated by any setter */
+    private _cached;
+    constructor(code: ErrorCode, message: string);
+    /** Add a recovery suggestion for the LLM agent */
+    suggest(suggestion: string): this;
+    /** List tool names the agent should try instead */
+    actions(...names: string[]): this;
+    /** Set error severity (default: 'error') */
+    severity(level: ErrorSeverity): this;
+    /** Set severity to 'critical' (stops agent execution) */
+    critical(): this;
+    /** Set severity to 'warning' (non-fatal guidance) */
+    warning(): this;
+    /** Add structured metadata details about the error */
+    details(data: Record<string, string | number | boolean>): this;
+    /** Suggest a retry delay in seconds for transient errors */
+    retryAfter(seconds: number): this;
+    /**
+     * Build the final {@link ToolResponse}.
+     *
+     * Note: The execution pipeline also accepts the builder instance
+     * directly and calls this method automatically.
+     */
+    build(): ToolResponse;
+    /** @internal Ensure the response is built and cached */
+    private _ensureBuilt;
+    /** Implementation of ToolResponse for direct return in handlers */
+    get content(): readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    get isError(): boolean | undefined;
+}
+//# sourceMappingURL=ErrorBuilder.d.ts.map

package/dist/core/builder/ErrorBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/ErrorBuilder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAuC;gBAE1C,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;IAK5C,kDAAkD;IAClD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMjC,mDAAmD;IACnD,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAMjC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAMpC,yDAAyD;IACzD,QAAQ,IAAI,IAAI;IAEhB,qDAAqD;IACrD,OAAO,IAAI,IAAI;IAEf,sDAAsD;IACtD,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI;IAQ9D,4DAA4D;IAC5D,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC;;;;;OAKG;IACH,KAAK,IAAI,YAAY;IAmBrB,wDAAwD;IACxD,OAAO,CAAC,YAAY;IAKpB,mEAAmE;IACnE,IAAI,OAAO;;;QAA0C;IACrD,IAAI,OAAO,wBAA0C;CACxD"}

package/dist/core/builder/ErrorBuilder.js

@@ -0,0 +1,99 @@
+import { toolError } from '../response.js';
+/**
+ * ErrorBuilder — Fluent API for Self-Healing Errors
+ *
+ * Provides a chaining interface to construct structured tool errors
+ * with recovery suggestions, available actions, and metadata.
+ *
+ * Designed to be used via `f.error()` in a tool handler.
+ *
+ * @example
+ * ```typescript
+ * return f.error('NOT_FOUND', `Project "${id}" missing`)
+ *     .suggest('Check the ID and try again')
+ *     .actions('projects.list')
+ *     .critical();
+ * ```
+ */
+export class ErrorBuilder {
+    _message;
+    _code;
+    _suggestion;
+    _actions = [];
+    _severity = 'error';
+    _details = {};
+    _retryAfter;
+    /** @internal Cached build result — invalidated by any setter */
+    _cached = undefined;
+    constructor(code, message) {
+        this._code = code;
+        this._message = message;
+    }
+    /** Add a recovery suggestion for the LLM agent */
+    suggest(suggestion) {
+        this._suggestion = suggestion;
+        this._cached = undefined;
+        return this;
+    }
+    /** List tool names the agent should try instead */
+    actions(...names) {
+        this._actions.push(...names);
+        this._cached = undefined;
+        return this;
+    }
+    /** Set error severity (default: 'error') */
+    severity(level) {
+        this._severity = level;
+        this._cached = undefined;
+        return this;
+    }
+    /** Set severity to 'critical' (stops agent execution) */
+    critical() { return this.severity('critical'); }
+    /** Set severity to 'warning' (non-fatal guidance) */
+    warning() { return this.severity('warning'); }
+    /** Add structured metadata details about the error */
+    details(data) {
+        for (const [key, value] of Object.entries(data)) {
+            this._details[key] = String(value);
+        }
+        this._cached = undefined;
+        return this;
+    }
+    /** Suggest a retry delay in seconds for transient errors */
+    retryAfter(seconds) {
+        this._retryAfter = seconds;
+        this._cached = undefined;
+        return this;
+    }
+    /**
+     * Build the final {@link ToolResponse}.
+     *
+     * Note: The execution pipeline also accepts the builder instance
+     * directly and calls this method automatically.
+     */
+    build() {
+        const opts = {
+            message: this._message,
+            severity: this._severity,
+        };
+        if (this._suggestion)
+            opts.suggestion = this._suggestion;
+        if (this._actions.length > 0)
+            opts.availableActions = this._actions;
+        if (Object.keys(this._details).length > 0)
+            opts.details = this._details;
+        if (this._retryAfter !== undefined)
+            opts.retryAfter = this._retryAfter;
+        return toolError(this._code, opts);
+    }
+    /** @internal Ensure the response is built and cached */
+    _ensureBuilt() {
+        if (!this._cached)
+            this._cached = this.build();
+        return this._cached;
+    }
+    /** Implementation of ToolResponse for direct return in handlers */
+    get content() { return this._ensureBuilt().content; }
+    get isError() { return this._ensureBuilt().isError; }
+}
+//# sourceMappingURL=ErrorBuilder.js.map

package/dist/core/builder/ErrorBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBuilder.js","sourceRoot":"","sources":["../../../src/core/builder/ErrorBuilder.ts"],"names":[],"mappings":"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"}

package/dist/core/builder/FluentRouter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * FluentRouter — Prefix Grouping for Fluent Tools
+ *
+ * Eliminates repetitive `'users.'` prefixes across dozens of tools.
+ * A router shares a common prefix, description, and middleware chain
+ * across all child tools.
+ *
+ * @example
+ * ```typescript
+ * const f = initVurb<AppContext>();
+ *
+ * const users = f.router('users')
+ *     .describe('User management')
+ *     .use(requireAuth);
+ *
+ * // Tool name: "users", action: "list"
+ * const listUsers = users.query('list')
+ *     .input({ limit: f.number() })
+ *     .resolve(async ({ input }) => { ... });
+ *
+ * // Tool name: "users", action: "delete"
+ * const deleteUser = users.mutation('delete')
+ *     .input({ id: f.string() })
+ *     .resolve(async ({ input }) => { ... });
+ * ```
+ *
+ * @module
+ */
+import { type MiddlewareFn } from '../types.js';
+import { type MiddlewareDefinition } from '../middleware/ContextDerivation.js';
+import { FluentToolBuilder } from './FluentToolBuilder.js';
+/**
+ * Fluent router that shares prefix, description, and middleware
+ * across child tools created via `.query()`, `.mutation()`, `.action()`.
+ *
+ * @typeParam TContext - Base application context
+ */
+export declare class FluentRouter<TContext> {
+    /** @internal */ readonly _prefix: string;
+    /** @internal */ _description?: string;
+    /** @internal */ _middlewares: MiddlewareFn<TContext>[];
+    /** @internal */ _tags: string[];
+    constructor(prefix: string);
+    /**
+     * Set the shared description for all tools in this router.
+     *
+     * @param text - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(text: string): this;
+    /**
+     * Add middleware shared by all tools in this router.
+     *
+     * Accepts both `MiddlewareDefinition` from `f.middleware()` and
+     * raw `MiddlewareFn` functions.
+     *
+     * @param mw - Middleware function or MiddlewareDefinition
+     * @returns Router with narrowed `TContext` type (when using MiddlewareDefinition)
+     */
+    use<TDerived extends Record<string, unknown>>(mw: MiddlewareDefinition<TContext, TDerived>): FluentRouter<TContext & TDerived>;
+    use(mw: MiddlewareFn<TContext>): this;
+    /**
+     * Set capability tags shared by all tools in this router.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags: string[]): this;
+    /**
+     * Create a read-only query tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'list'` → tool name `'prefix.list'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    query(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a destructive mutation tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'delete'` → tool name `'prefix.delete'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    mutation(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a neutral action tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'update'` → tool name `'prefix.update'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    action(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a FluentToolBuilder with inherited router config.
+     * @internal
+     */
+    private _createBuilder;
+}
+//# sourceMappingURL=FluentRouter.d.ts.map