@frontmcp/plugins 0.4.1 → 0.5.1

package/src/codecall/tools/describe.schema.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const describeToolDescription = "Get input/output schemas for tools from search results.\n\nINPUT: toolNames: string[] - tool names from search\nOUTPUT per tool: inputSchema (JSON Schema), outputSchema (JSON Schema), usageExamples (up to 5 callTool examples)\n\nIMPORTANT: If notFound array is non-empty \u2192 re-search with corrected queries.\nFLOW: search \u2192 describe \u2192 execute/invoke";
+export declare const describeToolInputSchema: z.ZodObject<{
+    toolNames: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type DescribeToolInput = z.infer<typeof describeToolInputSchema>;
+export declare const describeToolOutputSchema: z.ZodObject<{
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        appId: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        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>;
+        }, z.core.$strip>>;
+        usageExamples: z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+            code: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    notFound: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DescribeToolOutput = z.infer<typeof describeToolOutputSchema>;

package/src/codecall/tools/describe.schema.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeToolOutputSchema = exports.describeToolInputSchema = exports.describeToolDescription = void 0;
+// file: libs/plugins/src/codecall/tools/describe.schema.ts
+const zod_1 = require("zod");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+exports.describeToolDescription = `Get input/output schemas for tools from search results.
+
+INPUT: toolNames: string[] - tool names from search
+OUTPUT per tool: inputSchema (JSON Schema), outputSchema (JSON Schema), usageExamples (up to 5 callTool examples)
+
+IMPORTANT: If notFound array is non-empty → re-search with corrected queries.
+FLOW: search → describe → execute/invoke`;
+exports.describeToolInputSchema = zod_1.z.object({
+    toolNames: zod_1.z
+        .array(zod_1.z.string())
+        .min(1)
+        .superRefine((toolNames, ctx) => {
+        const seen = new Set();
+        const duplicates = new Set();
+        for (const name of toolNames) {
+            if (seen.has(name)) {
+                duplicates.add(name);
+            }
+            seen.add(name);
+        }
+        if (duplicates.size > 0) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `Duplicate tool names are not allowed: ${Array.from(duplicates).join(', ')}`,
+            });
+        }
+    })
+        .describe('Array of unique tool names (from codecall:search results) to fetch their detailed schemas and usage examples. Example: ["users:list", "billing:getInvoice"]'),
+});
+exports.describeToolOutputSchema = zod_1.z.object({
+    tools: zod_1.z
+        .array(zod_1.z.object({
+        name: zod_1.z.string().describe('Tool name to be used in callTool() within codecall:execute scripts'),
+        appId: zod_1.z.string().describe('The app ID this tool belongs to'),
+        description: zod_1.z.string().describe('Detailed description of what this tool does'),
+        inputSchema: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.unknown())
+            .nullable()
+            .describe('JSON Schema object describing the tool input parameters'),
+        outputSchema: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.unknown())
+            .nullable()
+            .describe('JSON Schema object describing the tool output structure'),
+        annotations: types_js_1.ToolAnnotationsSchema.optional().describe('MCP tool annotations (metadata)'),
+        usageExamples: zod_1.z
+            .array(zod_1.z.object({
+            description: zod_1.z.string().describe('Description of what this example demonstrates'),
+            code: zod_1.z
+                .string()
+                .describe('JavaScript code example showing how to call this tool using callTool(). Format: const result = await callTool("tool:name", { ...params });'),
+        }))
+            .max(5)
+            .describe('Up to 5 practical examples of how to use this tool in a codecall:execute script'),
+    }))
+        .describe('Array of tool descriptions with schemas and usage examples'),
+    notFound: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Tool names that were requested but not found in the index. Check these for typos.'),
+});
+//# sourceMappingURL=describe.schema.js.map

package/src/codecall/tools/describe.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.schema.js","sourceRoot":"","sources":["../../../../src/codecall/tools/describe.schema.ts"],"names":[],"mappings":";;;AAAA,2DAA2D;AAC3D,6BAAwB;AACxB,iEAA2E;AAE9D,QAAA,uBAAuB,GAAG;;;;;;yCAME,CAAC;AAE7B,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,SAAS,EAAE,OAAC;SACT,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,WAAW,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnB,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;gBAC3B,OAAO,EAAE,yCAAyC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aACtF,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;SACD,QAAQ,CACP,6JAA6J,CAC9J;CACJ,CAAC,CAAC;AAIU,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,OAAC;SACL,KAAK,CACJ,OAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oEAAoE,CAAC;QAC/F,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QAC7D,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAC/E,WAAW,EAAE,OAAC;aACX,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC;aAC/B,QAAQ,EAAE;aACV,QAAQ,CAAC,yDAAyD,CAAC;QACtE,YAAY,EAAE,OAAC;aACZ,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC;aAC/B,QAAQ,EAAE;aACV,QAAQ,CAAC,yDAAyD,CAAC;QACtE,WAAW,EAAE,gCAAqB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QACzF,aAAa,EAAE,OAAC;aACb,KAAK,CACJ,OAAC,CAAC,MAAM,CAAC;YACP,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;YACjF,IAAI,EAAE,OAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,4IAA4I,CAC7I;SACJ,CAAC,CACH;aACA,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,iFAAiF,CAAC;KAC/F,CAAC,CACH;SACA,QAAQ,CAAC,4DAA4D,CAAC;IACzE,QAAQ,EAAE,OAAC;SACR,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,mFAAmF,CAAC;CACjG,CAAC,CAAC","sourcesContent":["// file: libs/plugins/src/codecall/tools/describe.schema.ts\nimport { z } from 'zod';\nimport { ToolAnnotationsSchema } from '@modelcontextprotocol/sdk/types.js';\n\nexport const describeToolDescription = `Get input/output schemas for tools from search results.\n\nINPUT: toolNames: string[] - tool names from search\nOUTPUT per tool: inputSchema (JSON Schema), outputSchema (JSON Schema), usageExamples (up to 5 callTool examples)\n\nIMPORTANT: If notFound array is non-empty → re-search with corrected queries.\nFLOW: search → describe → execute/invoke`;\n\nexport const describeToolInputSchema = z.object({\n  toolNames: z\n    .array(z.string())\n    .min(1)\n    .superRefine((toolNames, ctx) => {\n      const seen = new Set<string>();\n      const duplicates = new Set<string>();\n      for (const name of toolNames) {\n        if (seen.has(name)) {\n          duplicates.add(name);\n        }\n        seen.add(name);\n      }\n      if (duplicates.size > 0) {\n        ctx.addIssue({\n          code: z.ZodIssueCode.custom,\n          message: `Duplicate tool names are not allowed: ${Array.from(duplicates).join(', ')}`,\n        });\n      }\n    })\n    .describe(\n      'Array of unique tool names (from codecall:search results) to fetch their detailed schemas and usage examples. Example: [\"users:list\", \"billing:getInvoice\"]',\n    ),\n});\n\nexport type DescribeToolInput = z.infer<typeof describeToolInputSchema>;\n\nexport const describeToolOutputSchema = z.object({\n  tools: z\n    .array(\n      z.object({\n        name: z.string().describe('Tool name to be used in callTool() within codecall:execute scripts'),\n        appId: z.string().describe('The app ID this tool belongs to'),\n        description: z.string().describe('Detailed description of what this tool does'),\n        inputSchema: z\n          .record(z.string(), z.unknown())\n          .nullable()\n          .describe('JSON Schema object describing the tool input parameters'),\n        outputSchema: z\n          .record(z.string(), z.unknown())\n          .nullable()\n          .describe('JSON Schema object describing the tool output structure'),\n        annotations: ToolAnnotationsSchema.optional().describe('MCP tool annotations (metadata)'),\n        usageExamples: z\n          .array(\n            z.object({\n              description: z.string().describe('Description of what this example demonstrates'),\n              code: z\n                .string()\n                .describe(\n                  'JavaScript code example showing how to call this tool using callTool(). Format: const result = await callTool(\"tool:name\", { ...params });',\n                ),\n            }),\n          )\n          .max(5)\n          .describe('Up to 5 practical examples of how to use this tool in a codecall:execute script'),\n      }),\n    )\n    .describe('Array of tool descriptions with schemas and usage examples'),\n  notFound: z\n    .array(z.string())\n    .optional()\n    .describe('Tool names that were requested but not found in the index. Check these for typos.'),\n});\n\nexport type DescribeToolOutput = z.infer<typeof describeToolOutputSchema>;\n"]}

package/src/codecall/tools/describe.tool.d.ts

@@ -0,0 +1,35 @@
+import { ToolContext } from '@frontmcp/sdk';
+import { DescribeToolInput, DescribeToolOutput } from './describe.schema';
+export default class DescribeTool extends ToolContext {
+    execute(input: DescribeToolInput): Promise<DescribeToolOutput>;
+    /**
+     * Get the input schema for a tool, converting from Zod to JSON Schema.
+     * This ensures that property descriptions from .describe() are included.
+     *
+     * Priority:
+     * 1. Convert from tool.inputSchema (Zod) to get descriptions
+     * 2. Fall back to rawInputSchema if conversion fails
+     * 3. Return null if no schema available
+     */
+    private getInputSchema;
+    /**
+     * Convert a schema to JSON Schema format.
+     * Handles Zod schemas, raw shapes, and already-JSON-Schema objects.
+     *
+     * Uses Zod v4's built-in z.toJSONSchema() for conversion.
+     */
+    private toJsonSchema;
+    /**
+     * Extract app ID from tool metadata or owner.
+     */
+    private extractAppId;
+    /**
+     * Generate up to 5 usage examples for a tool.
+     *
+     * Priority:
+     * 1. User-provided examples from @Tool decorator metadata (up to 5)
+     * 2. Smart intent-based generation to fill remaining slots
+     * 3. Returns at least 1 example
+     */
+    private generateExamples;
+}

package/src/codecall/tools/describe.tool.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// file: libs/plugins/src/codecall/tools/describe.tool.ts
+const sdk_1 = require("@frontmcp/sdk");
+const v4_1 = require("zod/v4");
+const zod_1 = require("zod");
+const describe_schema_1 = require("./describe.schema");
+const utils_1 = require("../utils");
+const security_1 = require("../security");
+let DescribeTool = class DescribeTool extends sdk_1.ToolContext {
+    async execute(input) {
+        const { toolNames } = input;
+        const tools = [];
+        const notFound = [];
+        // Get all available tools from the registry
+        const allTools = this.scope.tools.getTools(true);
+        const toolMap = new Map(allTools.map((t) => [t.name, t]));
+        const fullNameMap = new Map(allTools.map((t) => [t.fullName, t]));
+        for (const toolName of toolNames) {
+            // Security: Don't allow describing CodeCall tools themselves
+            if ((0, security_1.isBlockedSelfReference)(toolName)) {
+                notFound.push(toolName);
+                continue;
+            }
+            // Find the tool by name or fullName
+            const tool = toolMap.get(toolName) || fullNameMap.get(toolName);
+            if (!tool) {
+                notFound.push(toolName);
+                continue;
+            }
+            // Extract app ID from tool owner or metadata
+            const appId = this.extractAppId(tool);
+            // Get input schema - convert from Zod to ensure descriptions are included
+            const inputSchema = this.getInputSchema(tool);
+            // Get output schema - convert from Zod if needed
+            const outputSchema = this.toJsonSchema(tool.outputSchema);
+            // Generate usage examples: user-provided > smart generation > basic fallback
+            const usageExamples = this.generateExamples(tool, inputSchema ?? undefined);
+            tools.push({
+                name: tool.name,
+                appId,
+                description: tool.metadata?.description || `Tool: ${tool.name}`,
+                inputSchema: inputSchema || null,
+                outputSchema: outputSchema || null,
+                annotations: tool.metadata?.annotations,
+                usageExamples,
+            });
+        }
+        return {
+            tools,
+            notFound: notFound.length > 0 ? notFound : undefined,
+        };
+    }
+    /**
+     * Get the input schema for a tool, converting from Zod to JSON Schema.
+     * This ensures that property descriptions from .describe() are included.
+     *
+     * Priority:
+     * 1. Convert from tool.inputSchema (Zod) to get descriptions
+     * 2. Fall back to rawInputSchema if conversion fails
+     * 3. Return null if no schema available
+     */
+    getInputSchema(tool) {
+        // First, try to convert from the Zod inputSchema to ensure descriptions are included
+        if (tool.inputSchema && typeof tool.inputSchema === 'object' && Object.keys(tool.inputSchema).length > 0) {
+            try {
+                // tool.inputSchema is a ZodRawShape (Record<string, ZodType>)
+                const firstValue = Object.values(tool.inputSchema)[0];
+                if (firstValue instanceof zod_1.ZodType) {
+                    // Convert Zod shape to JSON Schema - this preserves .describe() annotations
+                    return (0, v4_1.toJSONSchema)(zod_1.z.object(tool.inputSchema));
+                }
+            }
+            catch {
+                // Fall through to rawInputSchema
+            }
+        }
+        // Fall back to rawInputSchema if available
+        if (tool.rawInputSchema) {
+            return tool.rawInputSchema;
+        }
+        return null;
+    }
+    /**
+     * Convert a schema to JSON Schema format.
+     * Handles Zod schemas, raw shapes, and already-JSON-Schema objects.
+     *
+     * Uses Zod v4's built-in z.toJSONSchema() for conversion.
+     */
+    toJsonSchema(schema) {
+        if (!schema) {
+            return null;
+        }
+        // Check if it's a Zod schema
+        if (schema instanceof zod_1.ZodType) {
+            try {
+                // Use Zod v4's toJSONSchema conversion
+                return (0, v4_1.toJSONSchema)(schema);
+            }
+            catch {
+                // If conversion fails, return null
+                return null;
+            }
+        }
+        // Check if it's a raw Zod shape (Record<string, ZodTypeAny>)
+        if (typeof schema === 'object' && schema !== null && !Array.isArray(schema)) {
+            const obj = schema;
+            const firstValue = Object.values(obj)[0];
+            // If the first value is a ZodType, treat the whole thing as a raw shape
+            if (firstValue instanceof zod_1.ZodType) {
+                try {
+                    // Wrap in z.object and convert using Zod v4's toJSONSchema
+                    return (0, v4_1.toJSONSchema)(zod_1.z.object(obj));
+                }
+                catch {
+                    return null;
+                }
+            }
+            // Already a JSON Schema object
+            if ('type' in obj || 'properties' in obj || '$schema' in obj) {
+                return schema;
+            }
+        }
+        // String literal output schemas (like 'text', 'json', etc.) - not a JSON Schema
+        if (typeof schema === 'string') {
+            return null;
+        }
+        // Array output schemas - not directly convertible
+        if (Array.isArray(schema)) {
+            return null;
+        }
+        return null;
+    }
+    /**
+     * Extract app ID from tool metadata or owner.
+     */
+    extractAppId(tool) {
+        // Check codecall metadata first
+        if (tool.metadata?.codecall?.appId) {
+            return tool.metadata.codecall.appId;
+        }
+        // Check source metadata
+        if (tool.metadata?.source) {
+            return tool.metadata.source;
+        }
+        // Check owner
+        if (tool.owner?.id) {
+            return tool.owner.id;
+        }
+        // Extract from tool name (namespace:name -> namespace)
+        const nameParts = tool.name?.split(':');
+        if (nameParts && nameParts.length > 1) {
+            return nameParts[0];
+        }
+        return 'unknown';
+    }
+    /**
+     * Generate up to 5 usage examples for a tool.
+     *
+     * Priority:
+     * 1. User-provided examples from @Tool decorator metadata (up to 5)
+     * 2. Smart intent-based generation to fill remaining slots
+     * 3. Returns at least 1 example
+     */
+    generateExamples(tool, inputSchema) {
+        const result = [];
+        // Priority 1: Use user-provided examples from metadata (up to 5)
+        const examples = tool.metadata?.examples;
+        if (examples && Array.isArray(examples)) {
+            for (const ex of examples.slice(0, 5)) {
+                result.push({
+                    description: ex.description || 'Example usage',
+                    code: `const result = await callTool('${tool.name}', ${JSON.stringify(ex.input, null, 2)});
+return result;`,
+                });
+            }
+        }
+        // Priority 2: If fewer than 5 user examples, add smart-generated example
+        if (result.length < 5) {
+            result.push((0, utils_1.generateSmartExample)(tool.name, inputSchema, tool.metadata?.description));
+        }
+        return result.slice(0, 5);
+    }
+};
+DescribeTool = tslib_1.__decorate([
+    (0, sdk_1.Tool)({
+        name: 'codecall:describe',
+        cache: {
+            ttl: 60, // 1 minute
+            slideWindow: false,
+        },
+        codecall: {
+            enabledInCodeCall: false,
+            visibleInListTools: true,
+        },
+        description: describe_schema_1.describeToolDescription,
+        inputSchema: describe_schema_1.describeToolInputSchema,
+        outputSchema: describe_schema_1.describeToolOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    })
+], DescribeTool);
+exports.default = DescribeTool;
+//# sourceMappingURL=describe.tool.js.map

package/src/codecall/tools/describe.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.tool.js","sourceRoot":"","sources":["../../../../src/codecall/tools/describe.tool.ts"],"names":[],"mappings":"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","sourcesContent":["// file: libs/plugins/src/codecall/tools/describe.tool.ts\nimport { Tool, ToolContext, ToolEntry } from '@frontmcp/sdk';\nimport type { JSONSchema } from 'zod/v4/core';\nimport { toJSONSchema } from 'zod/v4';\n\n/** JSON Schema type from Zod v4 */\ntype JsonSchema = JSONSchema.JSONSchema;\nimport { z, ZodType } from 'zod';\nimport {\n  DescribeToolInput,\n  describeToolInputSchema,\n  DescribeToolOutput,\n  describeToolOutputSchema,\n  describeToolDescription,\n} from './describe.schema';\nimport { generateSmartExample } from '../utils';\nimport { isBlockedSelfReference } from '../security';\n\n@Tool({\n  name: 'codecall:describe',\n  cache: {\n    ttl: 60, // 1 minute\n    slideWindow: false,\n  },\n  codecall: {\n    enabledInCodeCall: false,\n    visibleInListTools: true,\n  },\n  description: describeToolDescription,\n  inputSchema: describeToolInputSchema,\n  outputSchema: describeToolOutputSchema,\n  annotations: {\n    readOnlyHint: true,\n    openWorldHint: true,\n  },\n})\nexport default class DescribeTool extends ToolContext {\n  async execute(input: DescribeToolInput): Promise<DescribeToolOutput> {\n    const { toolNames } = input;\n\n    const tools: DescribeToolOutput['tools'] = [];\n    const notFound: string[] = [];\n\n    // Get all available tools from the registry\n    const allTools = this.scope.tools.getTools(true);\n    const toolMap = new Map(allTools.map((t) => [t.name, t]));\n    const fullNameMap = new Map(allTools.map((t) => [t.fullName, t]));\n\n    for (const toolName of toolNames) {\n      // Security: Don't allow describing CodeCall tools themselves\n      if (isBlockedSelfReference(toolName)) {\n        notFound.push(toolName);\n        continue;\n      }\n\n      // Find the tool by name or fullName\n      const tool = toolMap.get(toolName) || fullNameMap.get(toolName);\n\n      if (!tool) {\n        notFound.push(toolName);\n        continue;\n      }\n\n      // Extract app ID from tool owner or metadata\n      const appId = this.extractAppId(tool);\n\n      // Get input schema - convert from Zod to ensure descriptions are included\n      const inputSchema = this.getInputSchema(tool);\n\n      // Get output schema - convert from Zod if needed\n      const outputSchema = this.toJsonSchema(tool.outputSchema);\n\n      // Generate usage examples: user-provided > smart generation > basic fallback\n      const usageExamples = this.generateExamples(tool, inputSchema ?? undefined);\n\n      tools.push({\n        name: tool.name,\n        appId,\n        description: tool.metadata?.description || `Tool: ${tool.name}`,\n        inputSchema: (inputSchema as Record<string, unknown>) || null,\n        outputSchema: (outputSchema as Record<string, unknown>) || null,\n        annotations: tool.metadata?.annotations,\n        usageExamples,\n      });\n    }\n\n    return {\n      tools,\n      notFound: notFound.length > 0 ? notFound : undefined,\n    };\n  }\n\n  /**\n   * Get the input schema for a tool, converting from Zod to JSON Schema.\n   * This ensures that property descriptions from .describe() are included.\n   *\n   * Priority:\n   * 1. Convert from tool.inputSchema (Zod) to get descriptions\n   * 2. Fall back to rawInputSchema if conversion fails\n   * 3. Return null if no schema available\n   */\n  private getInputSchema(tool: ToolEntry<any, any>): JsonSchema | null {\n    // First, try to convert from the Zod inputSchema to ensure descriptions are included\n    if (tool.inputSchema && typeof tool.inputSchema === 'object' && Object.keys(tool.inputSchema).length > 0) {\n      try {\n        // tool.inputSchema is a ZodRawShape (Record<string, ZodType>)\n        const firstValue = Object.values(tool.inputSchema)[0];\n        if (firstValue instanceof ZodType) {\n          // Convert Zod shape to JSON Schema - this preserves .describe() annotations\n          return toJSONSchema(z.object(tool.inputSchema as Record<string, ZodType>)) as JsonSchema;\n        }\n      } catch {\n        // Fall through to rawInputSchema\n      }\n    }\n\n    // Fall back to rawInputSchema if available\n    if (tool.rawInputSchema) {\n      return tool.rawInputSchema as JsonSchema;\n    }\n\n    return null;\n  }\n\n  /**\n   * Convert a schema to JSON Schema format.\n   * Handles Zod schemas, raw shapes, and already-JSON-Schema objects.\n   *\n   * Uses Zod v4's built-in z.toJSONSchema() for conversion.\n   */\n  private toJsonSchema(schema: unknown): JsonSchema | null {\n    if (!schema) {\n      return null;\n    }\n\n    // Check if it's a Zod schema\n    if (schema instanceof ZodType) {\n      try {\n        // Use Zod v4's toJSONSchema conversion\n        return toJSONSchema(schema);\n      } catch {\n        // If conversion fails, return null\n        return null;\n      }\n    }\n\n    // Check if it's a raw Zod shape (Record<string, ZodTypeAny>)\n    if (typeof schema === 'object' && schema !== null && !Array.isArray(schema)) {\n      const obj = schema as Record<string, unknown>;\n      const firstValue = Object.values(obj)[0];\n\n      // If the first value is a ZodType, treat the whole thing as a raw shape\n      if (firstValue instanceof ZodType) {\n        try {\n          // Wrap in z.object and convert using Zod v4's toJSONSchema\n          return toJSONSchema(z.object(obj as Record<string, ZodType>) as any) as JsonSchema;\n        } catch {\n          return null;\n        }\n      }\n\n      // Already a JSON Schema object\n      if ('type' in obj || 'properties' in obj || '$schema' in obj) {\n        return schema as JsonSchema;\n      }\n    }\n\n    // String literal output schemas (like 'text', 'json', etc.) - not a JSON Schema\n    if (typeof schema === 'string') {\n      return null;\n    }\n\n    // Array output schemas - not directly convertible\n    if (Array.isArray(schema)) {\n      return null;\n    }\n\n    return null;\n  }\n\n  /**\n   * Extract app ID from tool metadata or owner.\n   */\n  private extractAppId(tool: {\n    name?: string;\n    metadata?: { codecall?: { appId?: string }; source?: string };\n    owner?: { id?: string };\n  }): string {\n    // Check codecall metadata first\n    if (tool.metadata?.codecall?.appId) {\n      return tool.metadata.codecall.appId;\n    }\n\n    // Check source metadata\n    if (tool.metadata?.source) {\n      return tool.metadata.source;\n    }\n\n    // Check owner\n    if (tool.owner?.id) {\n      return tool.owner.id;\n    }\n\n    // Extract from tool name (namespace:name -> namespace)\n    const nameParts = tool.name?.split(':');\n    if (nameParts && nameParts.length > 1) {\n      return nameParts[0];\n    }\n\n    return 'unknown';\n  }\n\n  /**\n   * Generate up to 5 usage examples for a tool.\n   *\n   * Priority:\n   * 1. User-provided examples from @Tool decorator metadata (up to 5)\n   * 2. Smart intent-based generation to fill remaining slots\n   * 3. Returns at least 1 example\n   */\n  private generateExamples(\n    tool: ToolEntry<any, any>,\n    inputSchema?: JsonSchema,\n  ): Array<{ description: string; code: string }> {\n    const result: Array<{ description: string; code: string }> = [];\n\n    // Priority 1: Use user-provided examples from metadata (up to 5)\n    const examples = tool.metadata?.examples;\n    if (examples && Array.isArray(examples)) {\n      for (const ex of examples.slice(0, 5)) {\n        result.push({\n          description: ex.description || 'Example usage',\n          code: `const result = await callTool('${tool.name}', ${JSON.stringify(ex.input, null, 2)});\nreturn result;`,\n        });\n      }\n    }\n\n    // Priority 2: If fewer than 5 user examples, add smart-generated example\n    if (result.length < 5) {\n      result.push(generateSmartExample(tool.name, inputSchema, tool.metadata?.description));\n    }\n\n    return result.slice(0, 5);\n  }\n}\n"]}

package/src/codecall/tools/execute.schema.d.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+export declare const executeToolDescription = "Execute AgentScript (safe JS subset) for multi-tool orchestration.\n\nAPI: await callTool(name, args, opts?)\n- Default: throws on error\n- Safe mode: { throwOnError: false } \u2192 returns { success, data?, error? }\n\nEXAMPLE:\nconst users = await callTool('users:list', { active: true });\nconst results = [];\nfor (const u of users.items) {\n  const orders = await callTool('orders:list', { userId: u.id });\n  results.push({ id: u.id, total: orders.items.reduce((s,o) => s + o.amount, 0) });\n}\nreturn results;\n\nALLOWED: for, for-of, arrow fn, map/filter/reduce/find, Math.*, JSON.*, if/else, destructuring, spread, template literals\nBLOCKED: while, do-while, function decl, eval, require, fetch, setTimeout, process, globalThis\n\nERRORS: NOT_FOUND | VALIDATION | EXECUTION | TIMEOUT | ACCESS_DENIED\nSTATUS: ok | syntax_error | illegal_access | runtime_error | tool_error | timeout\nLIMITS: 10K iter/loop, 30s timeout, 100 calls max";
+export declare const executeToolInputSchema: z.ZodObject<{
+    script: z.ZodString;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ExecuteToolInput = z.infer<typeof executeToolInputSchema>;
+/**
+ * Result variants
+ */
+export declare const codeCallOkResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    result: z.ZodUnknown;
+    logs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const codeCallSyntaxErrorResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"syntax_error">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        location: z.ZodOptional<z.ZodObject<{
+            line: z.ZodNumber;
+            column: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const codeCallIllegalAccessResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"illegal_access">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"IllegalBuiltinAccess">, z.ZodLiteral<"DisallowedGlobal">, z.ZodString]>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const codeCallRuntimeErrorResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"runtime_error">;
+    error: z.ZodObject<{
+        source: z.ZodLiteral<"script">;
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const codeCallToolErrorResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"tool_error">;
+    error: z.ZodObject<{
+        source: z.ZodLiteral<"tool">;
+        toolName: z.ZodString;
+        toolInput: z.ZodUnknown;
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const codeCallTimeoutResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"timeout">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Discriminated union for the whole result
+ */
+export declare const executeToolOutputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    result: z.ZodUnknown;
+    logs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"syntax_error">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        location: z.ZodOptional<z.ZodObject<{
+            line: z.ZodNumber;
+            column: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"illegal_access">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"IllegalBuiltinAccess">, z.ZodLiteral<"DisallowedGlobal">, z.ZodString]>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"runtime_error">;
+    error: z.ZodObject<{
+        source: z.ZodLiteral<"script">;
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"tool_error">;
+    error: z.ZodObject<{
+        source: z.ZodLiteral<"tool">;
+        toolName: z.ZodString;
+        toolInput: z.ZodUnknown;
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"timeout">;
+    error: z.ZodObject<{
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "status">;
+/**
+ * Inferred types
+ * (you can export whichever ones you actually need)
+ */
+export type CodeCallOkResult = z.infer<typeof codeCallOkResultSchema>;
+export type CodeCallSyntaxErrorResult = z.infer<typeof codeCallSyntaxErrorResultSchema>;
+export type CodeCallIllegalAccessResult = z.infer<typeof codeCallIllegalAccessResultSchema>;
+export type CodeCallRuntimeErrorResult = z.infer<typeof codeCallRuntimeErrorResultSchema>;
+export type CodeCallToolErrorResult = z.infer<typeof codeCallToolErrorResultSchema>;
+export type CodeCallTimeoutResult = z.infer<typeof codeCallTimeoutResultSchema>;
+export type CodeCallExecuteResult = CodeCallOkResult | CodeCallSyntaxErrorResult | CodeCallIllegalAccessResult | CodeCallRuntimeErrorResult | CodeCallToolErrorResult | CodeCallTimeoutResult;

package/src/codecall/tools/execute.schema.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeToolOutputSchema = exports.codeCallTimeoutResultSchema = exports.codeCallToolErrorResultSchema = exports.codeCallRuntimeErrorResultSchema = exports.codeCallIllegalAccessResultSchema = exports.codeCallSyntaxErrorResultSchema = exports.codeCallOkResultSchema = exports.executeToolInputSchema = exports.executeToolDescription = void 0;
+// file: libs/plugins/src/codecall/tools/execute.schema.ts
+const zod_1 = require("zod");
+/** Minimum script length - at least a simple callTool invocation */
+const MIN_EXECUTE_SCRIPT_LENGTH = 'return callTool("a",{})'.length;
+exports.executeToolDescription = `Execute AgentScript (safe JS subset) for multi-tool orchestration.
+
+API: await callTool(name, args, opts?)
+- Default: throws on error
+- Safe mode: { throwOnError: false } → returns { success, data?, error? }
+
+EXAMPLE:
+const users = await callTool('users:list', { active: true });
+const results = [];
+for (const u of users.items) {
+  const orders = await callTool('orders:list', { userId: u.id });
+  results.push({ id: u.id, total: orders.items.reduce((s,o) => s + o.amount, 0) });
+}
+return results;
+
+ALLOWED: for, for-of, arrow fn, map/filter/reduce/find, Math.*, JSON.*, if/else, destructuring, spread, template literals
+BLOCKED: while, do-while, function decl, eval, require, fetch, setTimeout, process, globalThis
+
+ERRORS: NOT_FOUND | VALIDATION | EXECUTION | TIMEOUT | ACCESS_DENIED
+STATUS: ok | syntax_error | illegal_access | runtime_error | tool_error | timeout
+LIMITS: 10K iter/loop, 30s timeout, 100 calls max`;
+exports.executeToolInputSchema = zod_1.z.object({
+    script: zod_1.z
+        .string()
+        .min(MIN_EXECUTE_SCRIPT_LENGTH)
+        .max(100 * 1024) // 100 KB
+        .describe('JavaScript code to execute in the sandbox. Must return a value (implicitly or via explicit return). Use callTool(name, input) to invoke tools.'),
+    allowedTools: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Optional whitelist of tool names that can be called from this script. If not provided, all indexed tools are available. Example: ["users:list", "billing:getInvoice"]'),
+});
+/**
+ * Shared "payload" schemas
+ */
+const syntaxErrorPayloadSchema = zod_1.z.object({
+    message: zod_1.z.string(),
+    location: zod_1.z
+        .object({
+        line: zod_1.z.number(),
+        column: zod_1.z.number(),
+    })
+        .optional(),
+});
+const illegalAccessErrorPayloadSchema = zod_1.z.object({
+    message: zod_1.z.string(),
+    kind: zod_1.z.union([
+        zod_1.z.literal('IllegalBuiltinAccess'),
+        zod_1.z.literal('DisallowedGlobal'),
+        zod_1.z.string(), // same as your original type: 'A' | 'B' | string
+    ]),
+});
+const runtimeErrorPayloadSchema = zod_1.z.object({
+    source: zod_1.z.literal('script'),
+    message: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    stack: zod_1.z.string().optional(),
+});
+const toolErrorPayloadSchema = zod_1.z.object({
+    source: zod_1.z.literal('tool'),
+    toolName: zod_1.z.string(),
+    toolInput: zod_1.z.unknown(),
+    message: zod_1.z.string(),
+    code: zod_1.z.string().optional(),
+    details: zod_1.z.unknown().optional(),
+});
+const timeoutErrorPayloadSchema = zod_1.z.object({
+    message: zod_1.z.string(),
+});
+/**
+ * Result variants
+ */
+exports.codeCallOkResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('ok'),
+    result: zod_1.z.unknown(),
+    logs: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.codeCallSyntaxErrorResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('syntax_error'),
+    error: syntaxErrorPayloadSchema,
+});
+exports.codeCallIllegalAccessResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('illegal_access'),
+    error: illegalAccessErrorPayloadSchema,
+});
+exports.codeCallRuntimeErrorResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('runtime_error'),
+    error: runtimeErrorPayloadSchema,
+});
+exports.codeCallToolErrorResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('tool_error'),
+    error: toolErrorPayloadSchema,
+});
+exports.codeCallTimeoutResultSchema = zod_1.z.object({
+    status: zod_1.z.literal('timeout'),
+    error: timeoutErrorPayloadSchema,
+});
+/**
+ * Discriminated union for the whole result
+ */
+exports.executeToolOutputSchema = zod_1.z.discriminatedUnion('status', [
+    exports.codeCallOkResultSchema,
+    exports.codeCallSyntaxErrorResultSchema,
+    exports.codeCallIllegalAccessResultSchema,
+    exports.codeCallRuntimeErrorResultSchema,
+    exports.codeCallToolErrorResultSchema,
+    exports.codeCallTimeoutResultSchema,
+]);
+//# sourceMappingURL=execute.schema.js.map

package/src/codecall/tools/execute.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.schema.js","sourceRoot":"","sources":["../../../../src/codecall/tools/execute.schema.ts"],"names":[],"mappings":"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","sourcesContent":["// file: libs/plugins/src/codecall/tools/execute.schema.ts\nimport { z } from 'zod';\n\n/** Minimum script length - at least a simple callTool invocation */\nconst MIN_EXECUTE_SCRIPT_LENGTH = 'return callTool(\"a\",{})'.length;\n\nexport const executeToolDescription = `Execute AgentScript (safe JS subset) for multi-tool orchestration.\n\nAPI: await callTool(name, args, opts?)\n- Default: throws on error\n- Safe mode: { throwOnError: false } → returns { success, data?, error? }\n\nEXAMPLE:\nconst users = await callTool('users:list', { active: true });\nconst results = [];\nfor (const u of users.items) {\n  const orders = await callTool('orders:list', { userId: u.id });\n  results.push({ id: u.id, total: orders.items.reduce((s,o) => s + o.amount, 0) });\n}\nreturn results;\n\nALLOWED: for, for-of, arrow fn, map/filter/reduce/find, Math.*, JSON.*, if/else, destructuring, spread, template literals\nBLOCKED: while, do-while, function decl, eval, require, fetch, setTimeout, process, globalThis\n\nERRORS: NOT_FOUND | VALIDATION | EXECUTION | TIMEOUT | ACCESS_DENIED\nSTATUS: ok | syntax_error | illegal_access | runtime_error | tool_error | timeout\nLIMITS: 10K iter/loop, 30s timeout, 100 calls max`;\n\nexport const executeToolInputSchema = z.object({\n  script: z\n    .string()\n    .min(MIN_EXECUTE_SCRIPT_LENGTH)\n    .max(100 * 1024) // 100 KB\n    .describe(\n      'JavaScript code to execute in the sandbox. Must return a value (implicitly or via explicit return). Use callTool(name, input) to invoke tools.',\n    ),\n  allowedTools: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Optional whitelist of tool names that can be called from this script. If not provided, all indexed tools are available. Example: [\"users:list\", \"billing:getInvoice\"]',\n    ),\n});\n\nexport type ExecuteToolInput = z.infer<typeof executeToolInputSchema>;\n\n/**\n * Shared \"payload\" schemas\n */\nconst syntaxErrorPayloadSchema = z.object({\n  message: z.string(),\n  location: z\n    .object({\n      line: z.number(),\n      column: z.number(),\n    })\n    .optional(),\n});\n\nconst illegalAccessErrorPayloadSchema = z.object({\n  message: z.string(),\n  kind: z.union([\n    z.literal('IllegalBuiltinAccess'),\n    z.literal('DisallowedGlobal'),\n    z.string(), // same as your original type: 'A' | 'B' | string\n  ]),\n});\n\nconst runtimeErrorPayloadSchema = z.object({\n  source: z.literal('script'),\n  message: z.string(),\n  name: z.string().optional(),\n  stack: z.string().optional(),\n});\n\nconst toolErrorPayloadSchema = z.object({\n  source: z.literal('tool'),\n  toolName: z.string(),\n  toolInput: z.unknown(),\n  message: z.string(),\n  code: z.string().optional(),\n  details: z.unknown().optional(),\n});\n\nconst timeoutErrorPayloadSchema = z.object({\n  message: z.string(),\n});\n\n/**\n * Result variants\n */\nexport const codeCallOkResultSchema = z.object({\n  status: z.literal('ok'),\n  result: z.unknown(),\n  logs: z.array(z.string()).optional(),\n});\n\nexport const codeCallSyntaxErrorResultSchema = z.object({\n  status: z.literal('syntax_error'),\n  error: syntaxErrorPayloadSchema,\n});\n\nexport const codeCallIllegalAccessResultSchema = z.object({\n  status: z.literal('illegal_access'),\n  error: illegalAccessErrorPayloadSchema,\n});\n\nexport const codeCallRuntimeErrorResultSchema = z.object({\n  status: z.literal('runtime_error'),\n  error: runtimeErrorPayloadSchema,\n});\n\nexport const codeCallToolErrorResultSchema = z.object({\n  status: z.literal('tool_error'),\n  error: toolErrorPayloadSchema,\n});\n\nexport const codeCallTimeoutResultSchema = z.object({\n  status: z.literal('timeout'),\n  error: timeoutErrorPayloadSchema,\n});\n\n/**\n * Discriminated union for the whole result\n */\nexport const executeToolOutputSchema = z.discriminatedUnion('status', [\n  codeCallOkResultSchema,\n  codeCallSyntaxErrorResultSchema,\n  codeCallIllegalAccessResultSchema,\n  codeCallRuntimeErrorResultSchema,\n  codeCallToolErrorResultSchema,\n  codeCallTimeoutResultSchema,\n]);\n\n/**\n * Inferred types\n * (you can export whichever ones you actually need)\n */\nexport type CodeCallOkResult = z.infer<typeof codeCallOkResultSchema>;\nexport type CodeCallSyntaxErrorResult = z.infer<typeof codeCallSyntaxErrorResultSchema>;\nexport type CodeCallIllegalAccessResult = z.infer<typeof codeCallIllegalAccessResultSchema>;\nexport type CodeCallRuntimeErrorResult = z.infer<typeof codeCallRuntimeErrorResultSchema>;\nexport type CodeCallToolErrorResult = z.infer<typeof codeCallToolErrorResultSchema>;\nexport type CodeCallTimeoutResult = z.infer<typeof codeCallTimeoutResultSchema>;\n\nexport type CodeCallExecuteResult =\n  | CodeCallOkResult\n  | CodeCallSyntaxErrorResult\n  | CodeCallIllegalAccessResult\n  | CodeCallRuntimeErrorResult\n  | CodeCallToolErrorResult\n  | CodeCallTimeoutResult;\n"]}

package/src/codecall/tools/execute.tool.d.ts

@@ -0,0 +1,5 @@
+import { ToolContext } from '@frontmcp/sdk';
+import { CodeCallExecuteResult, ExecuteToolInput } from './execute.schema';
+export default class ExecuteTool extends ToolContext {
+    execute(input: ExecuteToolInput): Promise<CodeCallExecuteResult>;
+}