@frontmcp/sdk 0.4.1 → 0.5.1

package/src/common/metadata/tool.metadata.d.ts

@@ -1,5 +1,9 @@
-import { z, ZodObject } from 'zod';
-import type { JSONSchema7 } from 'json-schema';
+import { z } from 'zod';
+import type { JSONSchema } from 'zod/v4/core';
+/** JSON Schema type from Zod v4 */
+type JsonSchema = JSONSchema.JSONSchema;
+import { ToolUIConfig } from './tool-ui.metadata';
+import { ToolInputOf, ToolOutputOf } from '../decorators';
 declare global {
     /**
      * Declarative metadata extends to the an McpTool decorator.
@@ -7,6 +11,23 @@ declare global {
     interface ExtendFrontMcpToolMetadata {
     }
 }
+/**
+ * Example input/output pair for a tool, used in documentation and describe output.
+ */
+export interface ToolExample {
+    /**
+     * Description of what this example demonstrates.
+     */
+    description: string;
+    /**
+     * Example input values for the tool.
+     */
+    input: Record<string, unknown>;
+    /**
+     * Optional expected output for the example.
+     */
+    output?: unknown;
+}
 export interface ToolAnnotations {
     [x: string]: unknown;
     /**
@@ -57,20 +78,18 @@ type PrimitiveOutputType = 'string' | 'number' | 'date' | 'boolean' | z.ZodStrin
 type ImageOutputType = 'image';
 export declare const ImageOutputSchema: z.ZodObject<{
     type: z.ZodLiteral<"image">;
-    data: z.ZodEffects<z.ZodString, string, string>;
+    data: z.ZodString;
     mimeType: z.ZodString;
+    annotations: z.ZodOptional<z.ZodObject<{
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>>>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        lastModified: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
     _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "image";
-    data: string;
-    mimeType: string;
-    _meta?: Record<string, unknown> | undefined;
-}, {
-    type: "image";
-    data: string;
-    mimeType: string;
-    _meta?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export type ImageOutput = z.output<typeof ImageOutputSchema>;
 /**
  * Tool response type audio, will use the AudioContentSchema from MCP types
@@ -78,20 +97,18 @@ export type ImageOutput = z.output<typeof ImageOutputSchema>;
 type AudioOutputType = 'audio';
 export declare const AudioOutputSchema: z.ZodObject<{
     type: z.ZodLiteral<"audio">;
-    data: z.ZodEffects<z.ZodString, string, string>;
+    data: z.ZodString;
     mimeType: z.ZodString;
+    annotations: z.ZodOptional<z.ZodObject<{
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>>>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        lastModified: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
     _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "audio";
-    data: string;
-    mimeType: string;
-    _meta?: Record<string, unknown> | undefined;
-}, {
-    type: "audio";
-    data: string;
-    mimeType: string;
-    _meta?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export type AudioOutput = z.output<typeof AudioOutputSchema>;
 /**
  * Tool response type resource, will use the EmbeddedResourceSchema from MCP types
@@ -99,130 +116,59 @@ export type AudioOutput = z.output<typeof AudioOutputSchema>;
 type ResourceOutputType = 'resource';
 export declare const ResourceOutputSchema: z.ZodObject<{
     type: z.ZodLiteral<"resource">;
-    resource: z.ZodUnion<[z.ZodObject<z.objectUtil.extendShape<{
+    resource: z.ZodUnion<readonly [z.ZodObject<{
         uri: z.ZodString;
         mimeType: z.ZodOptional<z.ZodString>;
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, {
         text: z.ZodString;
-    }>, "strip", z.ZodTypeAny, {
-        uri: string;
-        text: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    }, {
-        uri: string;
-        text: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    }>, z.ZodObject<z.objectUtil.extendShape<{
+    }, z.core.$strip>, z.ZodObject<{
         uri: z.ZodString;
         mimeType: z.ZodOptional<z.ZodString>;
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, {
-        blob: z.ZodEffects<z.ZodString, string, string>;
-    }>, "strip", z.ZodTypeAny, {
-        uri: string;
-        blob: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    }, {
-        uri: string;
-        blob: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    }>]>;
+        blob: z.ZodString;
+    }, z.core.$strip>]>;
+    annotations: z.ZodOptional<z.ZodObject<{
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>>>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        lastModified: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
     _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "resource";
-    resource: {
-        uri: string;
-        text: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    } | {
-        uri: string;
-        blob: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    };
-    _meta?: Record<string, unknown> | undefined;
-}, {
-    type: "resource";
-    resource: {
-        uri: string;
-        text: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    } | {
-        uri: string;
-        blob: string;
-        _meta?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-    };
-    _meta?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export type ResourceOutput = z.output<typeof ResourceOutputSchema>;
 /**
  * Tool response type resource_link, will use the ResourceLinkSchema from MCP types
  */
 type ResourceLinkOutputType = 'resource_link';
 export declare const ResourceLinkOutputSchema: z.ZodObject<{
-    name: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-} & {
     uri: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     mimeType: z.ZodOptional<z.ZodString>;
-    _meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
-} & {
+    annotations: z.ZodOptional<z.ZodObject<{
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>>>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        lastModified: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+    _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
         src: z.ZodString;
         mimeType: z.ZodOptional<z.ZodString>;
-        sizes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        src: string;
-        mimeType?: string | undefined;
-        sizes?: string[] | undefined;
-    }, {
-        src: string;
-        mimeType?: string | undefined;
-        sizes?: string[] | undefined;
-    }>, "many">>;
-} & {
+        sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"resource_link">;
-}, "strip", z.ZodTypeAny, {
-    type: "resource_link";
-    name: string;
-    uri: string;
-    _meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
-    mimeType?: string | undefined;
-    icons?: {
-        src: string;
-        mimeType?: string | undefined;
-        sizes?: string[] | undefined;
-    }[] | undefined;
-    title?: string | undefined;
-    description?: string | undefined;
-}, {
-    type: "resource_link";
-    name: string;
-    uri: string;
-    _meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
-    mimeType?: string | undefined;
-    icons?: {
-        src: string;
-        mimeType?: string | undefined;
-        sizes?: string[] | undefined;
-    }[] | undefined;
-    title?: string | undefined;
-    description?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type ResourceLinkOutput = z.output<typeof ResourceLinkOutputSchema>;
 /**
  * Tool response type json, ZodRawShape for fast usage
  */
-type StructuredOutputType = z.ZodRawShape | z.ZodObject<any> | z.ZodArray<any> | z.ZodUnion<[ZodObject<any>, ...ZodObject<any>[]]> | z.ZodDiscriminatedUnion<any, any>;
+type StructuredOutputType = z.ZodRawShape | z.ZodObject<any> | z.ZodArray<z.ZodType> | z.ZodUnion<[z.ZodObject<any>, ...z.ZodObject<any>[]]> | z.ZodDiscriminatedUnion<z.ZodObject<any>[]>;
 export type ToolSingleOutputType = PrimitiveOutputType | ImageOutputType | AudioOutputType | ResourceOutputType | ResourceLinkOutputType | StructuredOutputType;
 /**
  * Default default tool schema is {}
@@ -255,7 +201,7 @@ export interface ToolMetadata<InSchema = ToolInputType, OutSchema extends ToolOu
      * Zod schema describing the expected input payload for the tool.
      * Used for validation and for generating automatic docs/UX.
      */
-    rawInputSchema?: JSONSchema7;
+    rawInputSchema?: JsonSchema;
     /**
      * Zod schema describing the structure of the tool's successful output.
      */
@@ -272,90 +218,55 @@ export interface ToolMetadata<InSchema = ToolInputType, OutSchema extends ToolOu
      * Default: false
      */
     hideFromDiscovery?: boolean;
+    /**
+     * Optional usage examples for the tool.
+     * These are used by codecall:describe to provide accurate usage examples.
+     * If provided, these take precedence over auto-generated examples.
+     */
+    examples?: ToolExample[];
+    ui?: ToolUIConfig<ToolInputOf<InSchema>, ToolOutputOf<OutSchema>>;
 }
 export declare const frontMcpToolMetadataSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    inputSchema: z.ZodType<Object, z.ZodTypeDef, Object>;
+    inputSchema: z.ZodCustom<Object, Object>;
     rawInputSchema: z.ZodOptional<z.ZodAny>;
-    outputSchema: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, z.ZodArray<z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, "many">]>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    outputSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+    }>, z.ZodEnum<{
+        image: "image";
+        audio: "audio";
+        resource: "resource";
+        resource_link: "resource_link";
+    }>]>, z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>, z.ZodRecord<z.ZodString, z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+    }>, z.ZodEnum<{
+        image: "image";
+        audio: "audio";
+        resource: "resource";
+        resource_link: "resource_link";
+    }>]>, z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>, z.ZodRecord<z.ZodString, z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>]>>]>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     annotations: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         readOnlyHint: z.ZodOptional<z.ZodBoolean>;
         destructiveHint: z.ZodOptional<z.ZodBoolean>;
         idempotentHint: z.ZodOptional<z.ZodBoolean>;
         openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">>>;
-    hideFromDiscovery: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodOptional<z.ZodString>;
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    inputSchema: z.ZodType<Object, z.ZodTypeDef, Object>;
-    rawInputSchema: z.ZodOptional<z.ZodAny>;
-    outputSchema: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, z.ZodArray<z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, "many">]>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    annotations: z.ZodOptional<z.ZodObject<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">>>;
-    hideFromDiscovery: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodOptional<z.ZodString>;
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    inputSchema: z.ZodType<Object, z.ZodTypeDef, Object>;
-    rawInputSchema: z.ZodOptional<z.ZodAny>;
-    outputSchema: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, z.ZodArray<z.ZodUnion<[z.ZodUnion<[z.ZodEnum<["string", "number", "date", "boolean"]>, z.ZodEnum<["image", "audio", "resource", "resource_link"]>]>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>, z.ZodRecord<z.ZodString, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>>]>, "many">]>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    annotations: z.ZodOptional<z.ZodObject<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        title: z.ZodOptional<z.ZodString>;
-        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-        destructiveHint: z.ZodOptional<z.ZodBoolean>;
-        idempotentHint: z.ZodOptional<z.ZodBoolean>;
-        openWorldHint: z.ZodOptional<z.ZodBoolean>;
-    }, z.ZodTypeAny, "passthrough">>>;
+    }, z.core.$loose>>;
     hideFromDiscovery: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.ZodTypeAny, "passthrough">>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        output: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    ui: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$loose>;
 export {};

package/src/common/metadata/tool.metadata.js

@@ -24,24 +24,19 @@ exports.ResourceLinkOutputSchema = types_js_1.ResourceLinkSchema;
  */
 const primitiveOutputLiteralSchema = zod_1.z.enum(['string', 'number', 'date', 'boolean']);
 const specialOutputLiteralSchema = zod_1.z.enum(['image', 'audio', 'resource', 'resource_link']);
-const outputLiteralSchema = zod_1.z.union([
-    primitiveOutputLiteralSchema,
-    specialOutputLiteralSchema,
-]);
+const outputLiteralSchema = zod_1.z.union([primitiveOutputLiteralSchema, specialOutputLiteralSchema]);
 // Any Zod schema instance (object, array, union, etc.)
 const zodSchemaInstanceSchema = zod_1.z.instanceof(zod_1.z.ZodType);
 // Raw shape: { field: z.string(), ... }
-const zodRawShapeSchema = zod_1.z.record(zodSchemaInstanceSchema);
-const toolSingleOutputSchema = zod_1.z.union([
-    outputLiteralSchema,
-    zodSchemaInstanceSchema,
-    zodRawShapeSchema,
-]);
+const zodRawShapeSchema = zod_1.z.record(zod_1.z.string(), zodSchemaInstanceSchema);
+const toolSingleOutputSchema = zod_1.z.union([outputLiteralSchema, zodSchemaInstanceSchema, zodRawShapeSchema]);
 // ToolOutputType = ToolSingleOutputType | ToolSingleOutputType[]
-const toolOutputSchema = zod_1.z.union([
-    toolSingleOutputSchema,
-    zod_1.z.array(toolSingleOutputSchema),
-]);
+const toolOutputSchema = zod_1.z.union([toolSingleOutputSchema, zod_1.z.array(toolSingleOutputSchema)]);
+const toolExampleSchema = zod_1.z.object({
+    description: zod_1.z.string(),
+    input: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    output: zod_1.z.unknown().optional(),
+});
 exports.frontMcpToolMetadataSchema = zod_1.z
     .object({
     id: zod_1.z.string().optional(),
@@ -53,6 +48,8 @@ exports.frontMcpToolMetadataSchema = zod_1.z
     tags: zod_1.z.array(zod_1.z.string().min(1)).optional(),
     annotations: mcpToolAnnotationsSchema.optional(),
     hideFromDiscovery: zod_1.z.boolean().optional().default(false),
+    examples: zod_1.z.array(toolExampleSchema).optional(),
+    ui: zod_1.z.looseObject({}).optional(),
 })
     .passthrough();
 //# sourceMappingURL=tool.metadata.js.map

package/src/common/metadata/tool.metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.metadata.js","sourceRoot":"","sources":["../../../../src/common/metadata/tool.metadata.ts"],"names":[],"mappings":";;;AAAA,6BAAmC;AAGnC,iEAK4C;AAmD5C,MAAM,wBAAwB,GAAG,OAAC;KAC/B,MAAM,CAAC;IACN,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,YAAY,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACpC,eAAe,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACvC,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACtC,aAAa,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACC,CAAC;KACxC,WAAW,EAAE,CAAC;AAmBJ,QAAA,iBAAiB,GAAG,6BAAkB,CAAC;AAOvC,QAAA,iBAAiB,GAAG,6BAAkB,CAAC;AAOvC,QAAA,oBAAoB,GAAG,iCAAsB,CAAC;AAO9C,QAAA,wBAAwB,GAAG,6BAAkB,CAAC;AAkF3D;;;;;GAKG;AAEH,MAAM,4BAA4B,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AACrF,MAAM,0BAA0B,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;AAE3F,MAAM,mBAAmB,GAAG,OAAC,CAAC,KAAK,CAAC;IAClC,4BAA4B;IAC5B,0BAA0B;CAC3B,CAAC,CAAC;AAEH,uDAAuD;AACvD,MAAM,uBAAuB,GAAG,OAAC,CAAC,UAAU,CAAC,OAAC,CAAC,OAAO,CAAC,CAAC;AAExD,wCAAwC;AACxC,MAAM,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAE5D,MAAM,sBAAsB,GAAG,OAAC,CAAC,KAAK,CAAC;IACrC,mBAAmB;IACnB,uBAAuB;IACvB,iBAAiB;CAClB,CAAC,CAAC;AAEH,iEAAiE;AACjE,MAAM,gBAAgB,GAAG,OAAC,CAAC,KAAK,CAAC;IAC/B,sBAAsB;IACtB,OAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;CAChC,CAAC,CAAC;AACU,QAAA,0BAA0B,GAAG,OAAC;KACxC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,OAAC,CAAC,UAAU,CAAC,MAAM,CAAC;IACjC,cAAc,EAAE,OAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAClC,YAAY,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IACzC,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,WAAW,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAChD,iBAAiB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACO,CAAC;KACjE,WAAW,EAAE,CAAC","sourcesContent":["import { z, ZodObject } from 'zod';\nimport { RawZodShape } from '../types';\nimport type { JSONSchema7 } from 'json-schema';\nimport {\n  ImageContentSchema,\n  AudioContentSchema,\n  ResourceLinkSchema,\n  EmbeddedResourceSchema,\n} from '@modelcontextprotocol/sdk/types.js';\n\ndeclare global {\n  /**\n   * Declarative metadata extends to the an McpTool decorator.\n   */\n  interface ExtendFrontMcpToolMetadata {}\n}\n\nexport interface ToolAnnotations {\n  [x: string]: unknown;\n\n  /**\n   * A human-readable title for the tool.\n   */\n  title?: string;\n  /**\n   * If true, the tool does not modify its environment.\n   *\n   * Default: false\n   */\n  readOnlyHint?: boolean;\n  /**\n   * If true, the tool may perform destructive updates to its environment.\n   * If false, the tool performs only additive updates.\n   *\n   * (This property is meaningful only when `readOnlyHint == false`)\n   *\n   * Default: true\n   */\n  destructiveHint?: boolean;\n  /**\n   * If true, calling the tool repeatedly with the same arguments\n   * will have no additional effect on the its environment.\n   *\n   * (This property is meaningful only when `readOnlyHint == false`)\n   *\n   * Default: false\n   */\n  idempotentHint?: boolean;\n  /**\n   * If true, this tool may interact with an \"open world\" of external\n   * entities. If false, the tool's domain of interaction is closed.\n   * For example, the world of a web search tool is open, whereas that\n   * of a memory tool is not.\n   *\n   * Default: true\n   */\n  openWorldHint?: boolean;\n}\n\nconst mcpToolAnnotationsSchema = z\n  .object({\n    title: z.string().optional(),\n    readOnlyHint: z.boolean().optional(),\n    destructiveHint: z.boolean().optional(),\n    idempotentHint: z.boolean().optional(),\n    openWorldHint: z.boolean().optional(),\n  } satisfies RawZodShape<ToolAnnotations>)\n  .passthrough();\n\n/**\n * Tool response type text: include if outputSchema is zod primitive types\n */\ntype PrimitiveOutputType =\n  | 'string'\n  | 'number'\n  | 'date'\n  | 'boolean'\n  | z.ZodString\n  | z.ZodNumber\n  | z.ZodBoolean\n  | z.ZodBigInt\n  | z.ZodDate;\n/**\n * Tool response type image, will use the ImageContentSchema from MCP types\n */\ntype ImageOutputType = 'image';\nexport const ImageOutputSchema = ImageContentSchema;\nexport type ImageOutput = z.output<typeof ImageOutputSchema>;\n\n/**\n * Tool response type audio, will use the AudioContentSchema from MCP types\n */\ntype AudioOutputType = 'audio';\nexport const AudioOutputSchema = AudioContentSchema;\nexport type AudioOutput = z.output<typeof AudioOutputSchema>;\n\n/**\n * Tool response type resource, will use the EmbeddedResourceSchema from MCP types\n */\ntype ResourceOutputType = 'resource';\nexport const ResourceOutputSchema = EmbeddedResourceSchema;\nexport type ResourceOutput = z.output<typeof ResourceOutputSchema>;\n\n/**\n * Tool response type resource_link, will use the ResourceLinkSchema from MCP types\n */\ntype ResourceLinkOutputType = 'resource_link';\nexport const ResourceLinkOutputSchema = ResourceLinkSchema;\nexport type ResourceLinkOutput = z.output<typeof ResourceLinkOutputSchema>;\n\n/**\n * Tool response type json, ZodRawShape for fast usage\n */\ntype StructuredOutputType =\n  | z.ZodRawShape\n  | z.ZodObject<any>\n  | z.ZodArray<any>\n  | z.ZodUnion<[ZodObject<any>, ...ZodObject<any>[]]>\n  | z.ZodDiscriminatedUnion<any, any>;\n\nexport type ToolSingleOutputType =\n  | PrimitiveOutputType\n  | ImageOutputType\n  | AudioOutputType\n  | ResourceOutputType\n  | ResourceLinkOutputType\n  | StructuredOutputType;\n\n/**\n * Default default tool schema is {}\n */\nexport type ToolOutputType = ToolSingleOutputType | ToolSingleOutputType[] | undefined;\nexport type ToolInputType = z.ZodRawShape;\n\n/**\n * Declarative metadata describing what an McpTool contributes.\n */\nexport interface ToolMetadata<InSchema = ToolInputType, OutSchema extends ToolOutputType = ToolOutputType>\n  extends ExtendFrontMcpToolMetadata {\n  /**\n   * Optional unique identifier for the tool.\n   * If omitted, a consumer may derive an ID from the class or file name.\n   */\n  id?: string;\n\n  /**\n   * Human‑readable name of the tool, used in UIs, logs, and discovery.\n   */\n  name: string;\n\n  /**\n   * Short summary describing what the tool does and when to use it.\n   */\n  description?: string;\n\n  /**\n   * Zod schema describing the expected input payload for the tool.\n   * Used for validation and for generating automatic docs/UX.\n   */\n  inputSchema: InSchema;\n  /**\n   * Zod schema describing the expected input payload for the tool.\n   * Used for validation and for generating automatic docs/UX.\n   */\n  rawInputSchema?: JSONSchema7;\n\n  /**\n   * Zod schema describing the structure of the tool's successful output.\n   */\n  outputSchema?: OutSchema;\n\n  /**\n   * Optional list of tags/labels that categorize the tool for discovery and filtering.\n   */\n  tags?: string[];\n\n  annotations?: ToolAnnotations;\n\n  /**\n   * If true, the tool will not be shown in the tool/list action results.\n   * this method can still be called directly with tool/call even if hidden.\n   * use case: tools that are intended to be private or internal. (usually for testing / private apis)\n   * Default: false\n   */\n  hideFromDiscovery?: boolean;\n}\n\n\n\n/**\n * Runtime schema for ToolSingleOutputType:\n *  - literals ('string', 'image', ...)\n *  - any Zod schema (ZodObject, ZodArray, etc.)\n *  - raw shapes (Record<string, ZodTypeAny>)\n */\n\nconst primitiveOutputLiteralSchema = z.enum(['string', 'number', 'date', 'boolean']);\nconst specialOutputLiteralSchema = z.enum(['image', 'audio', 'resource', 'resource_link']);\n\nconst outputLiteralSchema = z.union([\n  primitiveOutputLiteralSchema,\n  specialOutputLiteralSchema,\n]);\n\n// Any Zod schema instance (object, array, union, etc.)\nconst zodSchemaInstanceSchema = z.instanceof(z.ZodType);\n\n// Raw shape: { field: z.string(), ... }\nconst zodRawShapeSchema = z.record(zodSchemaInstanceSchema);\n\nconst toolSingleOutputSchema = z.union([\n  outputLiteralSchema,\n  zodSchemaInstanceSchema,\n  zodRawShapeSchema,\n]);\n\n// ToolOutputType = ToolSingleOutputType | ToolSingleOutputType[]\nconst toolOutputSchema = z.union([\n  toolSingleOutputSchema,\n  z.array(toolSingleOutputSchema),\n]);\nexport const frontMcpToolMetadataSchema = z\n  .object({\n    id: z.string().optional(),\n    name: z.string().min(1),\n    description: z.string().optional(),\n    inputSchema: z.instanceof(Object),\n    rawInputSchema: z.any().optional(),\n    outputSchema: toolOutputSchema.optional(),\n    tags: z.array(z.string().min(1)).optional(),\n    annotations: mcpToolAnnotationsSchema.optional(),\n    hideFromDiscovery: z.boolean().optional().default(false),\n  } satisfies RawZodShape<ToolMetadata, ExtendFrontMcpToolMetadata>)\n  .passthrough();\n"]}
+{"version":3,"file":"tool.metadata.js","sourceRoot":"","sources":["../../../../src/common/metadata/tool.metadata.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { RawZodShape } from '../types';\nimport type { JSONSchema } from 'zod/v4/core';\n\n/** JSON Schema type from Zod v4 */\ntype JsonSchema = JSONSchema.JSONSchema;\nimport {\n  ImageContentSchema,\n  AudioContentSchema,\n  ResourceLinkSchema,\n  EmbeddedResourceSchema,\n} from '@modelcontextprotocol/sdk/types.js';\nimport { ToolUIConfig } from './tool-ui.metadata';\nimport { ToolInputOf, ToolOutputOf } from '../decorators';\n\ndeclare global {\n  /**\n   * Declarative metadata extends to the an McpTool decorator.\n   */\n  interface ExtendFrontMcpToolMetadata {}\n}\n\n/**\n * Example input/output pair for a tool, used in documentation and describe output.\n */\nexport interface ToolExample {\n  /**\n   * Description of what this example demonstrates.\n   */\n  description: string;\n\n  /**\n   * Example input values for the tool.\n   */\n  input: Record<string, unknown>;\n\n  /**\n   * Optional expected output for the example.\n   */\n  output?: unknown;\n}\n\nexport interface ToolAnnotations {\n  [x: string]: unknown;\n\n  /**\n   * A human-readable title for the tool.\n   */\n  title?: string;\n  /**\n   * If true, the tool does not modify its environment.\n   *\n   * Default: false\n   */\n  readOnlyHint?: boolean;\n  /**\n   * If true, the tool may perform destructive updates to its environment.\n   * If false, the tool performs only additive updates.\n   *\n   * (This property is meaningful only when `readOnlyHint == false`)\n   *\n   * Default: true\n   */\n  destructiveHint?: boolean;\n  /**\n   * If true, calling the tool repeatedly with the same arguments\n   * will have no additional effect on the its environment.\n   *\n   * (This property is meaningful only when `readOnlyHint == false`)\n   *\n   * Default: false\n   */\n  idempotentHint?: boolean;\n  /**\n   * If true, this tool may interact with an \"open world\" of external\n   * entities. If false, the tool's domain of interaction is closed.\n   * For example, the world of a web search tool is open, whereas that\n   * of a memory tool is not.\n   *\n   * Default: true\n   */\n  openWorldHint?: boolean;\n}\n\nconst mcpToolAnnotationsSchema = z\n  .object({\n    title: z.string().optional(),\n    readOnlyHint: z.boolean().optional(),\n    destructiveHint: z.boolean().optional(),\n    idempotentHint: z.boolean().optional(),\n    openWorldHint: z.boolean().optional(),\n  } satisfies RawZodShape<ToolAnnotations>)\n  .passthrough();\n\n/**\n * Tool response type text: include if outputSchema is zod primitive types\n */\ntype PrimitiveOutputType =\n  | 'string'\n  | 'number'\n  | 'date'\n  | 'boolean'\n  | z.ZodString\n  | z.ZodNumber\n  | z.ZodBoolean\n  | z.ZodBigInt\n  | z.ZodDate;\n/**\n * Tool response type image, will use the ImageContentSchema from MCP types\n */\ntype ImageOutputType = 'image';\nexport const ImageOutputSchema = ImageContentSchema;\nexport type ImageOutput = z.output<typeof ImageOutputSchema>;\n\n/**\n * Tool response type audio, will use the AudioContentSchema from MCP types\n */\ntype AudioOutputType = 'audio';\nexport const AudioOutputSchema = AudioContentSchema;\nexport type AudioOutput = z.output<typeof AudioOutputSchema>;\n\n/**\n * Tool response type resource, will use the EmbeddedResourceSchema from MCP types\n */\ntype ResourceOutputType = 'resource';\nexport const ResourceOutputSchema = EmbeddedResourceSchema;\nexport type ResourceOutput = z.output<typeof ResourceOutputSchema>;\n\n/**\n * Tool response type resource_link, will use the ResourceLinkSchema from MCP types\n */\ntype ResourceLinkOutputType = 'resource_link';\nexport const ResourceLinkOutputSchema = ResourceLinkSchema;\nexport type ResourceLinkOutput = z.output<typeof ResourceLinkOutputSchema>;\n\n/**\n * Tool response type json, ZodRawShape for fast usage\n */\ntype StructuredOutputType =\n  | z.ZodRawShape\n  | z.ZodObject<any>\n  | z.ZodArray<z.ZodType>\n  | z.ZodUnion<[z.ZodObject<any>, ...z.ZodObject<any>[]]>\n  | z.ZodDiscriminatedUnion<z.ZodObject<any>[]>;\n\nexport type ToolSingleOutputType =\n  | PrimitiveOutputType\n  | ImageOutputType\n  | AudioOutputType\n  | ResourceOutputType\n  | ResourceLinkOutputType\n  | StructuredOutputType;\n\n/**\n * Default default tool schema is {}\n */\nexport type ToolOutputType = ToolSingleOutputType | ToolSingleOutputType[] | undefined;\nexport type ToolInputType = z.ZodRawShape;\n\n/**\n * Declarative metadata describing what an McpTool contributes.\n */\nexport interface ToolMetadata<InSchema = ToolInputType, OutSchema extends ToolOutputType = ToolOutputType>\n  extends ExtendFrontMcpToolMetadata {\n  /**\n   * Optional unique identifier for the tool.\n   * If omitted, a consumer may derive an ID from the class or file name.\n   */\n  id?: string;\n\n  /**\n   * Human‑readable name of the tool, used in UIs, logs, and discovery.\n   */\n  name: string;\n\n  /**\n   * Short summary describing what the tool does and when to use it.\n   */\n  description?: string;\n\n  /**\n   * Zod schema describing the expected input payload for the tool.\n   * Used for validation and for generating automatic docs/UX.\n   */\n  inputSchema: InSchema;\n  /**\n   * Zod schema describing the expected input payload for the tool.\n   * Used for validation and for generating automatic docs/UX.\n   */\n  rawInputSchema?: JsonSchema;\n\n  /**\n   * Zod schema describing the structure of the tool's successful output.\n   */\n  outputSchema?: OutSchema;\n\n  /**\n   * Optional list of tags/labels that categorize the tool for discovery and filtering.\n   */\n  tags?: string[];\n\n  annotations?: ToolAnnotations;\n\n  /**\n   * If true, the tool will not be shown in the tool/list action results.\n   * this method can still be called directly with tool/call even if hidden.\n   * use case: tools that are intended to be private or internal. (usually for testing / private apis)\n   * Default: false\n   */\n  hideFromDiscovery?: boolean;\n\n  /**\n   * Optional usage examples for the tool.\n   * These are used by codecall:describe to provide accurate usage examples.\n   * If provided, these take precedence over auto-generated examples.\n   */\n  examples?: ToolExample[];\n\n  ui?: ToolUIConfig<ToolInputOf<InSchema>, ToolOutputOf<OutSchema>>;\n}\n\n/**\n * Runtime schema for ToolSingleOutputType:\n *  - literals ('string', 'image', ...)\n *  - any Zod schema (ZodObject, ZodArray, etc.)\n *  - raw shapes (Record<string, ZodTypeAny>)\n */\n\nconst primitiveOutputLiteralSchema = z.enum(['string', 'number', 'date', 'boolean']);\nconst specialOutputLiteralSchema = z.enum(['image', 'audio', 'resource', 'resource_link']);\n\nconst outputLiteralSchema = z.union([primitiveOutputLiteralSchema, specialOutputLiteralSchema]);\n\n// Any Zod schema instance (object, array, union, etc.)\nconst zodSchemaInstanceSchema = z.instanceof(z.ZodType);\n\n// Raw shape: { field: z.string(), ... }\nconst zodRawShapeSchema = z.record(z.string(), zodSchemaInstanceSchema);\n\nconst toolSingleOutputSchema = z.union([outputLiteralSchema, zodSchemaInstanceSchema, zodRawShapeSchema]);\n\n// ToolOutputType = ToolSingleOutputType | ToolSingleOutputType[]\nconst toolOutputSchema = z.union([toolSingleOutputSchema, z.array(toolSingleOutputSchema)]);\nconst toolExampleSchema = z.object({\n  description: z.string(),\n  input: z.record(z.string(), z.unknown()),\n  output: z.unknown().optional(),\n});\n\nexport const frontMcpToolMetadataSchema = z\n  .object({\n    id: z.string().optional(),\n    name: z.string().min(1),\n    description: z.string().optional(),\n    inputSchema: z.instanceof(Object),\n    rawInputSchema: z.any().optional(),\n    outputSchema: toolOutputSchema.optional(),\n    tags: z.array(z.string().min(1)).optional(),\n    annotations: mcpToolAnnotationsSchema.optional(),\n    hideFromDiscovery: z.boolean().optional().default(false),\n    examples: z.array(toolExampleSchema).optional(),\n    ui: z.looseObject({}).optional(),\n  } satisfies RawZodShape<ToolMetadata, ExtendFrontMcpToolMetadata>)\n  .passthrough();\n"]}

package/src/common/providers/base-config.provider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type-safe dotted path builder for nested object access
+ * Examples: 'vm.preset', 'embedding.strategy', 'directCalls.enabled'
+ */
+export type DottedPath<T, Prefix extends string = ''> = T extends object ? {
+    [K in keyof T & string]: T[K] extends object ? `${Prefix}${K}` | DottedPath<T[K], `${Prefix}${K}.`> : `${Prefix}${K}`;
+}[keyof T & string] : never;
+/**
+ * Get the type at a dotted path
+ */
+export type PathValue<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? PathValue<T[Key], Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * Base configuration provider with type-safe path lookup and convict-like API
+ */
+export declare abstract class BaseConfig<TConfig extends object> {
+    protected readonly config: TConfig;
+    constructor(config: TConfig);
+    /**
+     * Get the complete configuration object
+     */
+    getAll(): TConfig;
+    /**
+     * Get a value using dotted path notation (convict-like)
+     * @example
+     * config.get('vm.preset') // returns 'secure'
+     * config.get('embedding.strategy') // returns 'tfidf'
+     * config.get('directCalls.enabled') // returns true
+     * config.get('vm.timeout', 5000) // returns value or 5000 if undefined
+     */
+    get<P extends DottedPath<TConfig>>(path: P): PathValue<TConfig, P>;
+    get<P extends DottedPath<TConfig>>(path: P, defaultValue: PathValue<TConfig, P>): PathValue<TConfig, P>;
+    /**
+     * Check if a path exists in the configuration
+     * @example
+     * config.has('vm.preset') // returns true
+     * config.has('nonexistent.path') // returns false
+     */
+    has(path: string): boolean;
+    /**
+     * Get a value with a default fallback
+     * @example
+     * config.getOrDefault('vm.timeout', 5000)
+     */
+    getOrDefault<P extends DottedPath<TConfig>>(path: P, defaultValue: PathValue<TConfig, P>): PathValue<TConfig, P>;
+    /**
+     * Get a required value (throws if undefined)
+     * @example
+     * config.getRequired('vm.preset')
+     * config.getOrThrow('vm.preset')
+     */
+    getRequired<P extends DottedPath<TConfig>>(path: P): PathValue<TConfig, P>;
+    /**
+     * Alias for getRequired - Get a required value (throws if undefined)
+     * @example
+     * config.getOrThrow('vm.preset')
+     */
+    getOrThrow<P extends DottedPath<TConfig>>(path: P): PathValue<TConfig, P>;
+    /**
+     * Get a nested object at a path
+     * @example
+     * config.getSection('vm') // returns entire vm config
+     */
+    getSection<K extends keyof TConfig>(section: K): TConfig[K];
+    /**
+     * Check if the configuration matches a specific value at a path
+     * @example
+     * config.matches('vm.preset', 'secure') // returns true/false
+     */
+    matches<P extends DottedPath<TConfig>>(path: P, value: PathValue<TConfig, P>): boolean;
+    /**
+     * Get multiple values at once
+     * @example
+     * config.getMany(['vm.preset', 'embedding.strategy', 'topK'])
+     */
+    getMany<P extends DottedPath<TConfig>>(paths: P[]): Record<P, PathValue<TConfig, P>>;
+    /**
+     * Convert configuration to JSON
+     */
+    toJSON(): TConfig;
+    /**
+     * Convert configuration to string
+     */
+    toString(): string;
+}