glirastes 0.3.0 → 0.3.2

package/dist/cjs/server/adapters/nestjs/scanner/nestjs-scanner.d.ts

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+import type { AiEndpointToolDefinition, IntentModule } from '../../../../types.js';
+export interface NestJsScanOptions {
+    controllers: Function[];
+    apiPrefix?: string;
+}
+export interface NestJsScanResult {
+    tools: AiEndpointToolDefinition[];
+    modules: IntentModule[];
+    toolsByModule: Record<string, string[]>;
+}
+/**
+ * Scan decorated NestJS controllers and produce tool/module definitions.
+ * Works at build time without a running NestJS app.
+ */
+export declare function scanNestJsControllers(options: NestJsScanOptions): NestJsScanResult;

package/dist/cjs/server/adapters/nestjs/scanner/nestjs-scanner.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanNestJsControllers = scanNestJsControllers;
+require("reflect-metadata");
+const zod_1 = require("zod");
+const metadata_js_1 = require("../metadata.js");
+const schema_builder_js_1 = require("./schema-builder.js");
+const HTTP_METHOD_MAP = {
+    0: 'GET',
+    1: 'POST',
+    2: 'PUT',
+    3: 'DELETE',
+    4: 'PATCH',
+};
+/**
+ * Scan decorated NestJS controllers and produce tool/module definitions.
+ * Works at build time without a running NestJS app.
+ */
+function scanNestJsControllers(options) {
+    const apiPrefix = options.apiPrefix ?? '/api';
+    const allTools = [];
+    const moduleMap = new Map();
+    for (const controllerClass of options.controllers) {
+        const moduleMeta = (0, metadata_js_1.getAiModuleMeta)(controllerClass);
+        if (!moduleMeta)
+            continue;
+        const tools = (0, metadata_js_1.getAllAiTools)(controllerClass);
+        const controllerPath = Reflect.getMetadata('path', controllerClass) ?? '';
+        for (const tool of tools) {
+            const methodPath = Reflect.getMetadata('path', controllerClass.prototype[tool.methodName]) ?? '';
+            const fullPath = `${apiPrefix}/${controllerPath}/${methodPath}`
+                .replace(/\/+/g, '/')
+                .replace(/\/$/, '') || '/';
+            // Resolve HTTP method
+            const httpMethodNum = Reflect.getMetadata('method', controllerClass.prototype[tool.methodName]);
+            const httpMethod = tool.method ??
+                HTTP_METHOD_MAP[httpMethodNum ?? 0] ??
+                'GET';
+            // Resolve DTO schema
+            const paramTypes = Reflect.getMetadata('design:paramtypes', controllerClass.prototype, tool.methodName);
+            let inputSchema = zod_1.z.object({});
+            if (paramTypes) {
+                for (const pt of paramTypes) {
+                    if (pt && typeof pt === 'function' && (0, schema_builder_js_1.hasAiRelevantMeta)(pt)) {
+                        inputSchema = (0, schema_builder_js_1.buildZodSchemaFromDto)(pt);
+                        break;
+                    }
+                }
+            }
+            // Merge path parameters into input schema
+            const pathParams = (0, schema_builder_js_1.extractRouteParams)(controllerClass, tool.methodName);
+            if (pathParams.length > 0) {
+                const pathShape = {};
+                for (const paramName of pathParams) {
+                    if (!(inputSchema instanceof zod_1.z.ZodObject) || !(paramName in inputSchema.shape)) {
+                        pathShape[paramName] = zod_1.z.string().uuid().describe(`Path parameter: ${paramName}`);
+                    }
+                }
+                if (Object.keys(pathShape).length > 0) {
+                    inputSchema = inputSchema instanceof zod_1.z.ZodObject
+                        ? inputSchema.extend(pathShape)
+                        : zod_1.z.object(pathShape);
+                }
+            }
+            allTools.push({
+                id: `${moduleMeta.intent}.${tool.name}`,
+                toolName: tool.name,
+                module: tool.module ?? moduleMeta.intent,
+                sharedWith: tool.sharedWith,
+                description: tool.description,
+                method: httpMethod,
+                path: fullPath,
+                inputSchema,
+                needsApproval: tool.needsApproval,
+                uiActionOnSuccess: tool.uiActionOnSuccess,
+                uiPattern: tool.uiPattern,
+            });
+        }
+        // Build IntentModule
+        const intent = moduleMeta.intent;
+        const toolNames = tools.map((t) => t.name);
+        const existing = moduleMap.get(intent);
+        if (existing) {
+            existing.toolNames.push(...toolNames);
+        }
+        else {
+            const meta = {
+                classification: moduleMeta.classification,
+                execution: moduleMeta.execution,
+                systemPrompt: moduleMeta.systemPrompt,
+            };
+            moduleMap.set(intent, { type: intent, toolNames, meta });
+        }
+    }
+    // Expand sharedWith
+    const toolsByModule = {};
+    for (const [intent, mod] of moduleMap) {
+        toolsByModule[intent] = [...mod.toolNames];
+    }
+    for (const tool of allTools) {
+        if (!tool.sharedWith)
+            continue;
+        for (const sharedModule of tool.sharedWith) {
+            if (!toolsByModule[sharedModule]) {
+                toolsByModule[sharedModule] = [];
+            }
+            if (!toolsByModule[sharedModule].includes(tool.toolName)) {
+                toolsByModule[sharedModule].push(tool.toolName);
+            }
+        }
+    }
+    return {
+        tools: allTools,
+        modules: Array.from(moduleMap.values()),
+        toolsByModule,
+    };
+}

package/dist/cjs/server/adapters/nestjs/scanner/schema-builder.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import 'reflect-metadata';
+/**
+ * Build a Zod schema from a DTO class.
+ *
+ * Resolution order per property:
+ * 1. @AiParam — explicit AI-specific description (highest priority)
+ * 2. @ApiProperty — Swagger metadata as fallback (description, required, constraints)
+ * 3. design:type — TypeScript type metadata for base type inference
+ *
+ * Constraints from @ApiProperty (minLength, maxLength, minimum, maximum, enum)
+ * are applied as Zod validations AND appended to the property description so
+ * the AI model knows the constraints before generating values.
+ */
+export declare function buildZodSchemaFromDto(dtoClass: Function): z.ZodObject<Record<string, z.ZodTypeAny>>;
+/**
+ * Check whether a DTO class has any AI-relevant property metadata
+ * (either @AiParam or @ApiProperty decorators).
+ */
+export declare function hasAiRelevantMeta(dtoClass: Function): boolean;
+/**
+ * Extract @Param() parameter names from a controller method's route arguments metadata.
+ * NestJS stores route arguments under '__routeArguments__' with keys like "5:0" where
+ * 5 = RouteParamtypes.PARAM. The `data` field holds the parameter name (e.g., 'id').
+ */
+export declare function extractRouteParams(controllerClass: Function, methodName: string): string[];

package/dist/cjs/server/adapters/nestjs/scanner/schema-builder.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildZodSchemaFromDto = buildZodSchemaFromDto;
+exports.hasAiRelevantMeta = hasAiRelevantMeta;
+exports.extractRouteParams = extractRouteParams;
+const zod_1 = require("zod");
+require("reflect-metadata");
+const metadata_js_1 = require("../metadata.js");
+/**
+ * Metadata key used by @nestjs/swagger's @ApiProperty decorator.
+ * Properties decorated with @ApiProperty store their options under this key.
+ */
+const SWAGGER_API_MODEL_PROPERTIES = 'swagger/apiModelProperties';
+const SWAGGER_API_MODEL_PROPERTIES_ARRAY = 'swagger/apiModelPropertiesArray';
+/**
+ * Read @ApiProperty metadata for all properties on a DTO class.
+ * Returns an array of property descriptors with description and constraints.
+ */
+function getSwaggerPropertyMeta(dtoClass) {
+    const propertyNames = Reflect.getMetadata(SWAGGER_API_MODEL_PROPERTIES_ARRAY, dtoClass.prototype);
+    if (!propertyNames || propertyNames.length === 0)
+        return [];
+    const result = [];
+    for (const rawKey of propertyNames) {
+        // Swagger stores keys with a ':' prefix (e.g., ':name', ':description')
+        const propertyKey = rawKey.startsWith(':') ? rawKey.slice(1) : rawKey;
+        const meta = Reflect.getMetadata(SWAGGER_API_MODEL_PROPERTIES, dtoClass.prototype, propertyKey);
+        if (meta) {
+            result.push({ propertyKey, meta });
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Build a Zod schema from a DTO class.
+ *
+ * Resolution order per property:
+ * 1. @AiParam — explicit AI-specific description (highest priority)
+ * 2. @ApiProperty — Swagger metadata as fallback (description, required, constraints)
+ * 3. design:type — TypeScript type metadata for base type inference
+ *
+ * Constraints from @ApiProperty (minLength, maxLength, minimum, maximum, enum)
+ * are applied as Zod validations AND appended to the property description so
+ * the AI model knows the constraints before generating values.
+ */
+function buildZodSchemaFromDto(dtoClass) {
+    const aiParams = (0, metadata_js_1.getAiParamMeta)(dtoClass);
+    const swaggerProps = getSwaggerPropertyMeta(dtoClass);
+    const mergedParams = buildMergedParamList(aiParams, swaggerProps);
+    if (mergedParams.length === 0)
+        return zod_1.z.object({});
+    const shape = {};
+    for (const param of mergedParams) {
+        const designType = Reflect.getMetadata('design:type', dtoClass.prototype, param.propertyKey);
+        let fieldSchema = buildFieldSchema(designType, param.constraints);
+        // Build enriched description: base description + constraint hints
+        const enrichedDescription = buildEnrichedDescription(param.description, param.constraints);
+        if (enrichedDescription) {
+            fieldSchema = fieldSchema.describe(enrichedDescription);
+        }
+        // Apply optional
+        if (param.isOptional) {
+            fieldSchema = fieldSchema.optional();
+        }
+        else {
+            fieldSchema = detectOptionalByDefault(dtoClass, param.propertyKey, fieldSchema);
+        }
+        shape[param.propertyKey] = fieldSchema;
+    }
+    return zod_1.z.object(shape);
+}
+/**
+ * Check whether a DTO class has any AI-relevant property metadata
+ * (either @AiParam or @ApiProperty decorators).
+ */
+function hasAiRelevantMeta(dtoClass) {
+    if ((0, metadata_js_1.getAiParamMeta)(dtoClass).length > 0)
+        return true;
+    if (getSwaggerPropertyMeta(dtoClass).length > 0)
+        return true;
+    return false;
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+function buildMergedParamList(aiParams, swaggerProps) {
+    const aiParamMap = new Map(aiParams.map((p) => [p.propertyKey, p]));
+    const swaggerMap = new Map(swaggerProps.map((p) => [p.propertyKey, p.meta]));
+    // Collect all unique property keys (preserving order)
+    const allKeys = new Set();
+    for (const p of aiParams)
+        allKeys.add(p.propertyKey);
+    for (const p of swaggerProps)
+        allKeys.add(p.propertyKey);
+    const result = [];
+    for (const key of allKeys) {
+        const aiParam = aiParamMap.get(key);
+        const swaggerMeta = swaggerMap.get(key);
+        const description = aiParam?.description ?? swaggerMeta?.description ?? '';
+        const isOptional = swaggerMeta?.required === false;
+        const constraints = {};
+        if (swaggerMeta) {
+            if (swaggerMeta.minLength !== undefined)
+                constraints.minLength = swaggerMeta.minLength;
+            if (swaggerMeta.maxLength !== undefined)
+                constraints.maxLength = swaggerMeta.maxLength;
+            if (swaggerMeta.minimum !== undefined)
+                constraints.minimum = swaggerMeta.minimum;
+            if (swaggerMeta.maximum !== undefined)
+                constraints.maximum = swaggerMeta.maximum;
+            if (swaggerMeta.enum !== undefined)
+                constraints.enum = swaggerMeta.enum;
+        }
+        result.push({ propertyKey: key, description, isOptional, constraints });
+    }
+    return result;
+}
+/**
+ * Build a Zod field schema with constraints applied.
+ */
+function buildFieldSchema(designType, constraints) {
+    const baseSchema = designTypeToZod(designType);
+    // Apply constraints based on the Zod type
+    if (baseSchema instanceof zod_1.z.ZodString) {
+        return applyStringConstraints(baseSchema, constraints);
+    }
+    if (baseSchema instanceof zod_1.z.ZodNumber) {
+        return applyNumberConstraints(baseSchema, constraints);
+    }
+    if (constraints.enum && constraints.enum.length > 0) {
+        return buildEnumSchema(constraints.enum);
+    }
+    return baseSchema;
+}
+function applyStringConstraints(schema, constraints) {
+    let s = schema;
+    if (constraints.minLength !== undefined)
+        s = s.min(constraints.minLength);
+    if (constraints.maxLength !== undefined)
+        s = s.max(constraints.maxLength);
+    // Enum overrides string type entirely
+    if (constraints.enum && constraints.enum.length > 0) {
+        return buildEnumSchema(constraints.enum);
+    }
+    return s;
+}
+function applyNumberConstraints(schema, constraints) {
+    let n = schema;
+    if (constraints.minimum !== undefined)
+        n = n.min(constraints.minimum);
+    if (constraints.maximum !== undefined)
+        n = n.max(constraints.maximum);
+    return n;
+}
+function buildEnumSchema(values) {
+    const stringValues = values.filter((v) => typeof v === 'string');
+    if (stringValues.length >= 2) {
+        return zod_1.z.enum(stringValues);
+    }
+    if (stringValues.length === 1) {
+        return zod_1.z.literal(stringValues[0]);
+    }
+    return zod_1.z.unknown();
+}
+/**
+ * Append constraint hints to the base description so the AI model
+ * knows the validation rules before generating values.
+ */
+function buildEnrichedDescription(baseDescription, constraints) {
+    const hints = [];
+    if (constraints.minLength !== undefined && constraints.maxLength !== undefined) {
+        hints.push(`${constraints.minLength}-${constraints.maxLength} characters`);
+    }
+    else if (constraints.minLength !== undefined) {
+        hints.push(`min ${constraints.minLength} characters`);
+    }
+    else if (constraints.maxLength !== undefined) {
+        hints.push(`max ${constraints.maxLength} characters`);
+    }
+    if (constraints.minimum !== undefined && constraints.maximum !== undefined) {
+        hints.push(`range ${constraints.minimum}-${constraints.maximum}`);
+    }
+    else if (constraints.minimum !== undefined) {
+        hints.push(`min ${constraints.minimum}`);
+    }
+    else if (constraints.maximum !== undefined) {
+        hints.push(`max ${constraints.maximum}`);
+    }
+    if (constraints.enum && constraints.enum.length > 0) {
+        const values = constraints.enum
+            .filter((v) => typeof v === 'string' || typeof v === 'number')
+            .map((v) => String(v));
+        if (values.length > 0) {
+            hints.push(`one of: ${values.join(', ')}`);
+        }
+    }
+    if (hints.length === 0)
+        return baseDescription;
+    const constraintSuffix = `(${hints.join('; ')})`;
+    return baseDescription
+        ? `${baseDescription} ${constraintSuffix}`
+        : constraintSuffix;
+}
+function designTypeToZod(designType) {
+    if (!designType)
+        return zod_1.z.unknown();
+    switch (designType) {
+        case String:
+            return zod_1.z.string();
+        case Number:
+            return zod_1.z.number();
+        case Boolean:
+            return zod_1.z.boolean();
+        case Array:
+            return zod_1.z.array(zod_1.z.unknown());
+        case Date:
+            return zod_1.z.string();
+        default:
+            return zod_1.z.unknown();
+    }
+}
+/**
+ * Extract @Param() parameter names from a controller method's route arguments metadata.
+ * NestJS stores route arguments under '__routeArguments__' with keys like "5:0" where
+ * 5 = RouteParamtypes.PARAM. The `data` field holds the parameter name (e.g., 'id').
+ */
+function extractRouteParams(controllerClass, methodName) {
+    const ROUTE_ARGS_METADATA = '__routeArguments__';
+    const PARAM_TYPE = '5'; // RouteParamtypes.PARAM
+    const routeArgs = Reflect.getMetadata(ROUTE_ARGS_METADATA, controllerClass, methodName) ?? {};
+    const params = [];
+    for (const [key, value] of Object.entries(routeArgs)) {
+        if (key.startsWith(`${PARAM_TYPE}:`) && value.data) {
+            params.push(value.data);
+        }
+    }
+    return params;
+}
+/**
+ * Check if a property has a default value on a constructed instance.
+ * If so, mark it as optional.
+ */
+function detectOptionalByDefault(dtoClass, propertyKey, fieldSchema) {
+    try {
+        const constructed = new dtoClass();
+        if (constructed &&
+            typeof constructed === 'object' &&
+            propertyKey in constructed) {
+            return fieldSchema.optional();
+        }
+    }
+    catch {
+        // Cannot construct, skip optional detection
+    }
+    return fieldSchema;
+}

package/dist/cjs/server/adapters/nestjs/swagger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Walks an OpenAPI document and merges `@AiTool` decorator metadata
+ * into each matching operation as an `x-ai` extension.
+ *
+ * Mutates `document` in place.
+ */
+export declare function applyAiExtensions(document: Record<string, unknown>, controllers: Array<new (...args: unknown[]) => unknown>): void;

package/dist/cjs/server/adapters/nestjs/swagger.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAiExtensions = applyAiExtensions;
+const metadata_js_1 = require("./metadata.js");
+/**
+ * Walks an OpenAPI document and merges `@AiTool` decorator metadata
+ * into each matching operation as an `x-ai` extension.
+ *
+ * Mutates `document` in place.
+ */
+function applyAiExtensions(document, controllers) {
+    const paths = document['paths'];
+    if (!paths)
+        return;
+    for (const controller of controllers) {
+        const moduleMeta = (0, metadata_js_1.getAiModuleMeta)(controller);
+        const tools = (0, metadata_js_1.getAllAiTools)(controller);
+        for (const tool of tools) {
+            const toolPath = tool.path;
+            const toolMethod = tool.method?.toLowerCase();
+            if (!toolPath || !toolMethod)
+                continue;
+            const pathItem = paths[toolPath];
+            if (!pathItem)
+                continue;
+            const operation = pathItem[toolMethod];
+            if (!operation)
+                continue;
+            const extension = {
+                enabled: true,
+                toolName: tool.name,
+                description: tool.description,
+                needsApproval: tool.needsApproval,
+                module: moduleMeta?.intent,
+            };
+            operation['x-ai'] = extension;
+        }
+    }
+}

package/dist/cjs/server/adapters/nextjs/context-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { ToolContext, RuntimeContext } from '../../../types.js';
+import { type InternalApiCaller, type NextInternalApiCallerOptions } from '../../core/index.js';
+/**
+ * Extract origin from a Next.js request.
+ * Checks x-forwarded-host/host headers, falls back to req.url.
+ */
+export declare function extractOrigin(req: Request): string;
+/**
+ * Build a RuntimeContext from a Next.js request.
+ */
+export declare function buildRuntimeContext(req: Request): RuntimeContext;
+/**
+ * Build a complete ToolContext from a Next.js request.
+ */
+export declare function buildToolContext(req: Request, options?: {
+    locale?: string;
+}): ToolContext;
+/**
+ * Create an InternalApiCaller from a Next.js request.
+ * Automatically extracts origin and cookies.
+ */
+export declare function createInternalApiCallerFromRequest(req: Request, overrides?: Partial<NextInternalApiCallerOptions>): InternalApiCaller;

package/dist/cjs/server/adapters/nextjs/context-helpers.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractOrigin = extractOrigin;
+exports.buildRuntimeContext = buildRuntimeContext;
+exports.buildToolContext = buildToolContext;
+exports.createInternalApiCallerFromRequest = createInternalApiCallerFromRequest;
+const index_js_1 = require("../../core/index.js");
+/**
+ * Extract origin from a Next.js request.
+ * Checks x-forwarded-host/host headers, falls back to req.url.
+ */
+function extractOrigin(req) {
+    const forwardedHost = req.headers.get('x-forwarded-host');
+    const forwardedProto = req.headers.get('x-forwarded-proto') ?? 'https';
+    if (forwardedHost) {
+        return `${forwardedProto}://${forwardedHost}`;
+    }
+    const host = req.headers.get('host');
+    if (host) {
+        const proto = host.startsWith('localhost') ? 'http' : 'https';
+        return `${proto}://${host}`;
+    }
+    try {
+        const url = new URL(req.url);
+        return url.origin;
+    }
+    catch {
+        return 'http://localhost:3000';
+    }
+}
+/**
+ * Build a RuntimeContext from a Next.js request.
+ */
+function buildRuntimeContext(req) {
+    return {
+        origin: extractOrigin(req),
+        cookieHeader: req.headers.get('cookie') ?? undefined,
+    };
+}
+/**
+ * Build a complete ToolContext from a Next.js request.
+ */
+function buildToolContext(req, options) {
+    return {
+        currentDate: new Date(),
+        locale: options?.locale ?? 'en-US',
+        runtime: buildRuntimeContext(req),
+    };
+}
+/**
+ * Create an InternalApiCaller from a Next.js request.
+ * Automatically extracts origin and cookies.
+ */
+function createInternalApiCallerFromRequest(req, overrides) {
+    return (0, index_js_1.createNextInternalApiCaller)({
+        origin: extractOrigin(req),
+        cookieHeader: req.headers.get('cookie') ?? undefined,
+        ...overrides,
+    });
+}

package/dist/cjs/server/adapters/nextjs/create-ai-chat-handler.d.ts

@@ -0,0 +1,94 @@
+import type { PiiShield } from '../../../types.js';
+import type { AiChatHandlerConfig, IntentRoutingResult, PipelineStepReport, PipelineResult, StepLimitSource } from './types.js';
+/**
+ * Callback that the consumer provides to stream the AI response.
+ * Receives the prepared context and returns a Response.
+ *
+ * This decouples the adapter from the `ai` SDK — the consumer
+ * calls streamText() themselves with full type safety.
+ */
+export interface StreamHandlerContext {
+    /** AI tools (output of toolsToAiTools, RBAC-filtered) */
+    tools: Record<string, unknown>;
+    /** Processed messages (after guardrails, sliced to context window) */
+    messages: unknown[];
+    /** Resolved system prompt string */
+    systemPrompt: string;
+    /** Resolved model (static or from model selector) */
+    model: unknown;
+    /** Max steps (explicit/module/safety-resolved) */
+    maxSteps: number;
+    /** Source used to resolve maxSteps */
+    stepLimitSource: StepLimitSource;
+    /** Whether to emit `data-step-report` events */
+    emitStepReports: boolean;
+    /** Optional per-step callback */
+    onStepReport?: (report: PipelineStepReport) => void;
+    /** Max output tokens */
+    maxOutputTokens: number;
+    /** Temperature */
+    temperature: number;
+    /** Max context messages for model-message preparation */
+    maxContextMessages: number;
+    /** Model tier from intent routing or pipeline */
+    modelTier?: string;
+    /** Intent routing result (legacy mode) */
+    routing?: IntentRoutingResult;
+    /** Pipeline result (pipeline mode) */
+    pipelineResult?: PipelineResult;
+    /** PII shield context for response de-anonymization */
+    piiShield?: {
+        shield: PiiShield;
+        sessionId: string;
+    };
+}
+/**
+ * Extended config that adds an optional streamHandler for full AI SDK control.
+ *
+ * When `streamHandler` is not provided, a built-in default is used that:
+ * - Converts UI messages to model messages via `prepareModelMessages()`
+ * - Wraps SDK tools via `wrapToolsForVercelAi()`
+ * - Calls `streamText()` and returns `createUIMessageStreamResponse()`
+ */
+export interface AiChatHandlerFullConfig extends AiChatHandlerConfig {
+    /**
+     * Custom stream handler. Receives prepared context, returns Response.
+     * This is where the consumer calls streamText() / toDataStreamResponse().
+     *
+     * When omitted, the built-in default handler is used.
+     */
+    streamHandler?: (ctx: StreamHandlerContext) => Promise<Response>;
+}
+/**
+ * Default soft cap on reasoning steps when no module-level or explicit
+ * `maxSteps` is configured. Acts as a last-line safety against runaway
+ * tool loops; not as a normal-operation cap (modules default to 4 via
+ * EXECUTION_DEFAULTS). Override per request via `createAiChatHandler({
+ * safetyMaxSteps })`.
+ */
+export declare const DEFAULT_SAFETY_MAX_STEPS = 24;
+export declare function resolveStepLimit(options: {
+    moduleMaxSteps?: number | null;
+    configuredMaxSteps?: number | null;
+    safetyMaxSteps?: number;
+}): {
+    maxSteps: number;
+    stepLimitSource: StepLimitSource;
+};
+/**
+ * Creates a complete Next.js App Router POST handler for AI chat.
+ *
+ * Supports two modes:
+ *
+ * **Pipeline mode** (Pro): When `pipeline` is provided, uses the server-pro
+ * pipeline for guardrails, intent classification, tool selection, and model
+ * selection.
+ *
+ * **Legacy mode**: When no `pipeline` is provided, uses the original
+ * `guardrails` + `intentRouter` flow.
+ *
+ * The SDK does not perform authentication or authorization. Tools forward the
+ * caller's cookies to backend APIs via `runtime.cookieHeader`; permission
+ * checks happen on the backend.
+ */
+export declare function createAiChatHandler(config: AiChatHandlerFullConfig): (req: Request) => Promise<Response>;