@frontmcp/plugin-codecall 0.0.1 → 0.7.1

package/services/output-sanitizer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Output Sanitizer for CodeCall
+ *
+ * Sanitizes script outputs to prevent information leakage through:
+ * - Error messages with stack traces or file paths
+ * - Large outputs that could contain sensitive data
+ * - Recursive structures that could cause DoS
+ *
+ * Security considerations:
+ * - All sanitization is defensive (fail-safe)
+ * - Outputs are truncated, not rejected
+ * - Circular references are handled
+ * - Prototype pollution is prevented
+ */
+/**
+ * Configuration for output sanitization.
+ */
+export interface OutputSanitizerConfig {
+    /**
+     * Maximum depth for nested objects/arrays.
+     * @default 10
+     */
+    maxDepth: number;
+    /**
+     * Maximum length for string values.
+     * @default 10000
+     */
+    maxStringLength: number;
+    /**
+     * Maximum number of keys in an object.
+     * @default 100
+     */
+    maxObjectKeys: number;
+    /**
+     * Maximum number of items in an array.
+     * @default 1000
+     */
+    maxArrayLength: number;
+    /**
+     * Maximum total size of serialized output in bytes.
+     * @default 1MB
+     */
+    maxTotalSize: number;
+    /**
+     * Remove error stack traces.
+     * @default true
+     */
+    removeStackTraces: boolean;
+    /**
+     * Remove file paths from strings.
+     * @default true
+     */
+    removeFilePaths: boolean;
+}
+/**
+ * Default sanitization configuration.
+ */
+export declare const DEFAULT_SANITIZER_CONFIG: OutputSanitizerConfig;
+/**
+ * Result of sanitization.
+ */
+export interface SanitizationResult<T> {
+    /** Sanitized value */
+    value: T;
+    /** Whether any sanitization was applied */
+    wasModified: boolean;
+    /** Warnings about what was sanitized */
+    warnings: string[];
+}
+/**
+ * Sanitize output from CodeCall script execution.
+ *
+ * @param output - Raw output from script
+ * @param config - Sanitization configuration
+ * @returns Sanitized output with metadata
+ */
+export declare function sanitizeOutput<T = unknown>(output: unknown, config?: Partial<OutputSanitizerConfig>): SanitizationResult<T>;
+/**
+ * Quick check if a value needs sanitization.
+ * Used for optimization - skip sanitization for simple values.
+ */
+export declare function needsSanitization(value: unknown): boolean;
+/**
+ * Sanitize a log message (less aggressive than output sanitization).
+ */
+export declare function sanitizeLogMessage(message: string, maxLength?: number): string;
+//# sourceMappingURL=output-sanitizer.d.ts.map

package/services/output-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-sanitizer.d.ts","sourceRoot":"","sources":["../../src/services/output-sanitizer.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,qBAQrC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,sBAAsB;IACtB,KAAK,EAAE,CAAC,CAAC;IACT,2CAA2C;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,MAAM,EAAE,OAAO,EACf,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC1C,kBAAkB,CAAC,CAAC,CAAC,CAiCvB;AAyND;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgBzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAoB3E"}

package/services/synonym-expansion.service.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Configuration for the SynonymExpansionService
+ */
+export interface SynonymExpansionConfig {
+    /**
+     * Additional synonym groups to include beyond defaults.
+     * Each group is an array of related terms.
+     */
+    additionalSynonyms?: ReadonlyArray<ReadonlyArray<string>>;
+    /**
+     * If true, completely replace default synonyms with additionalSynonyms.
+     * @default false
+     */
+    replaceDefaults?: boolean;
+    /**
+     * Maximum number of expanded terms per input term.
+     * Prevents query explosion.
+     * @default 5
+     */
+    maxExpansionsPerTerm?: number;
+}
+/**
+ * Lightweight synonym expansion service for improving TF-IDF search relevance.
+ * Zero dependencies, synchronous, and easily extensible.
+ *
+ * This service provides query-time synonym expansion to help TF-IDF-based
+ * search understand that semantically similar terms (like "add" and "create")
+ * should match the same tools.
+ */
+export declare class SynonymExpansionService {
+    private synonymMap;
+    private maxExpansions;
+    constructor(config?: SynonymExpansionConfig);
+    /**
+     * Build a bidirectional synonym map from groups.
+     * Each term maps to all other terms in its group(s).
+     */
+    private buildSynonymMap;
+    /**
+     * Get synonyms for a single term.
+     * Returns empty array if no synonyms found.
+     *
+     * @example
+     * getSynonyms('add') // ['create', 'new', 'insert', 'make']
+     */
+    getSynonyms(term: string): string[];
+    /**
+     * Expand a query string by adding synonyms for each term.
+     * Returns the expanded query string with original terms and their synonyms.
+     *
+     * @example
+     * expandQuery('add user') // 'add create new insert make user account member profile'
+     */
+    expandQuery(query: string): string;
+    /**
+     * Check if synonym expansion is available for any term in the query.
+     */
+    hasExpansions(query: string): boolean;
+    /**
+     * Get statistics about the synonym dictionary.
+     */
+    getStats(): {
+        termCount: number;
+        avgSynonymsPerTerm: number;
+    };
+}
+//# sourceMappingURL=synonym-expansion.service.d.ts.map

package/services/synonym-expansion.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synonym-expansion.service.d.ts","sourceRoot":"","sources":["../../src/services/synonym-expansion.service.ts"],"names":[],"mappings":"AAoTA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1D;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,GAAE,sBAA2B;IAW/C;;;OAGG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAYnC;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAoBlC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAKrC;;OAEG;IACH,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE;CAa9D"}

package/services/tool-search.service.d.ts

@@ -0,0 +1,196 @@
+import { ToolEntry, ScopeEntry } from '@frontmcp/sdk';
+import type { EmbeddingStrategy, CodeCallEmbeddingOptions, CodeCallMode } from '../codecall.types';
+import type { ToolSearch, ToolSearchResult as SymbolToolSearchResult, ToolSearchOptions as SymbolToolSearchOptions } from '../codecall.symbol';
+import { SynonymExpansionConfig } from './synonym-expansion.service';
+/**
+ * Search result for tool search
+ */
+export interface SearchResult {
+    tool: ToolEntry<any, any>;
+    score: number;
+    toolName: string;
+    qualifiedName: string;
+    appId?: string;
+}
+/**
+ * Search options for tool search
+ */
+export interface SearchOptions {
+    topK?: number;
+    appIds?: string[];
+    excludeToolNames?: string[];
+    minScore?: number;
+}
+/**
+ * Filter function type for including tools
+ */
+export type IncludeToolsFilter = (info: {
+    name: string;
+    appId?: string;
+    source?: string;
+    description?: string;
+    tags?: string[];
+}) => boolean;
+/**
+ * Configuration for tool search service
+ */
+export interface ToolSearchServiceConfig {
+    /**
+     * Embedding strategy to use
+     * @default 'tfidf'
+     */
+    strategy?: EmbeddingStrategy;
+    /**
+     * Full embedding options (alternative to just strategy)
+     */
+    embeddingOptions?: CodeCallEmbeddingOptions;
+    /**
+     * Default number of results to return
+     * @default 8
+     */
+    defaultTopK?: number;
+    /**
+     * Default similarity threshold
+     * @default 0.0
+     */
+    defaultSimilarityThreshold?: number;
+    /**
+     * CodeCall mode for filtering tools
+     * @default 'codecall_only'
+     */
+    mode?: CodeCallMode;
+    /**
+     * Optional filter function for including tools in the search index
+     */
+    includeTools?: IncludeToolsFilter;
+    /**
+     * Synonym expansion configuration.
+     * When enabled, queries are expanded with synonyms to improve search relevance.
+     * For example, "add user" will also match tools containing "create user".
+     * Only applies when strategy is 'tfidf' (ML already handles semantic similarity).
+     *
+     * Set to false to disable, or provide a config object to customize.
+     * @default { enabled: true } when strategy is 'tfidf'
+     */
+    synonymExpansion?: false | (SynonymExpansionConfig & {
+        enabled?: boolean;
+    });
+}
+/**
+ * Service that maintains a searchable index of tools from the ToolRegistry
+ * Supports both TF-IDF (lightweight, synchronous) and ML-based (semantic) embeddings
+ * Implements the ToolSearch interface for dependency injection
+ */
+export declare class ToolSearchService implements ToolSearch {
+    private static readonly MAX_SUBSCRIPTION_RETRIES;
+    private static readonly INITIAL_RETRY_DELAY_MS;
+    private static readonly MAX_RETRY_DELAY_MS;
+    private vectorDB;
+    private strategy;
+    private initialized;
+    private mlInitialized;
+    private config;
+    private scope;
+    private unsubscribe?;
+    private synonymService;
+    private subscriptionPromise;
+    private subscriptionResolved;
+    private subscriptionResolve;
+    private subscriptionReject;
+    private retryTimeoutId;
+    private disposed;
+    constructor(config: ToolSearchServiceConfig | undefined, scope: ScopeEntry);
+    /**
+     * Ensures the service is subscribed to tool changes before proceeding.
+     * Public methods should call this before accessing tools.
+     */
+    private ensureSubscribed;
+    /**
+     * Sets up subscription to tool changes with exponential backoff retry.
+     * Handles the case where scope.tools may not be available yet during plugin initialization.
+     */
+    private setupSubscription;
+    /**
+     * Subscribes to tool changes once scope.tools is available.
+     */
+    private subscribeToToolChanges;
+    /**
+     * Marks the subscription as resolved, allowing pending operations to proceed.
+     */
+    private markSubscribed;
+    /**
+     * Handles tool change events by reindexing all tools from the snapshot
+     */
+    private handleToolChange;
+    /**
+     * Determines if a tool should be indexed in the search database.
+     * Filters based on:
+     * - Excludes codecall:* meta-tools (they should not be searchable)
+     * - Mode-based filtering (codecall_only, codecall_opt_in, metadata_driven)
+     * - Per-tool metadata.codecall.enabledInCodeCall
+     * - Custom includeTools filter function
+     */
+    private shouldIndexTool;
+    /**
+     * Extract CodeCall-specific metadata from a tool.
+     */
+    private getCodeCallMetadata;
+    /**
+     * Initializes the search service by indexing all tools from the registry.
+     * NOTE: This method is now a no-op. Initialization is handled reactively
+     * via subscription to tool change events in the constructor.
+     * This method exists for interface compatibility.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Cleanup subscription and pending retries when service is destroyed
+     */
+    dispose(): void;
+    /**
+     * Extracts searchable text from a tool instance.
+     * Uses term weighting to improve relevance:
+     * - Description terms are heavily weighted (most important for semantic matching)
+     * - Tool name parts are tokenized and weighted
+     * - Tags provide additional context
+     */
+    private extractSearchableText;
+    /**
+     * Checks if a word is a common stop word that should not receive extra weighting.
+     * Uses module-level STOP_WORDS constant to avoid recreating the Set on each call.
+     */
+    private isStopWord;
+    /**
+     * Extracts app ID from tool's owner lineage
+     */
+    private extractAppId;
+    /**
+     * Searches for tools matching the query
+     * Implements the ToolSearch interface
+     */
+    search(query: string, options?: SymbolToolSearchOptions): Promise<SymbolToolSearchResult[]>;
+    /**
+     * Gets all indexed tool names
+     */
+    getAllToolNames(): string[];
+    /**
+     * Gets the total number of indexed tools
+     */
+    getTotalCount(): number;
+    /**
+     * Checks if a tool exists in the index
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Clears the entire index
+     */
+    clear(): void;
+    /**
+     * Get the current embedding strategy
+     */
+    getStrategy(): EmbeddingStrategy;
+    /**
+     * Check if the service is initialized
+     */
+    isInitialized(): boolean;
+}
+//# sourceMappingURL=tool-search.service.d.ts.map

package/services/tool-search.service.d.ts.map

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

package/tools/describe.schema.d.ts

@@ -0,0 +1,29 @@
+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>;
+//# sourceMappingURL=describe.schema.d.ts.map

package/tools/describe.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.schema.d.ts","sourceRoot":"","sources":["../../src/tools/describe.schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,uBAAuB,gXAMK,CAAC;AAE1C,eAAO,MAAM,uBAAuB;;iBAuBlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;iBAoCnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/tools/describe.tool.d.ts

@@ -0,0 +1,36 @@
+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;
+}
+//# sourceMappingURL=describe.tool.d.ts.map

package/tools/describe.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.tool.d.ts","sourceRoot":"","sources":["../../src/tools/describe.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,WAAW,EAAa,MAAM,eAAe,CAAC;AAO7D,OAAO,EACL,iBAAiB,EAEjB,kBAAkB,EAGnB,MAAM,mBAAmB,CAAC;AAsB3B,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,WAAW;IAC7C,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuDpE;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAkDpB;;OAEG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;CAyBzB"}

package/tools/execute.schema.d.ts

@@ -0,0 +1,116 @@
+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;
+//# sourceMappingURL=execute.schema.d.ts.map

package/tools/execute.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.schema.d.ts","sourceRoot":"","sources":["../../src/tools/execute.schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,sBAAsB,o7BAoBe,CAAC;AAEnD,eAAO,MAAM,sBAAsB;;;iBAcjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AA4CtE;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;iBAIjC,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;;;;;iBAG1C,CAAC;AAEH,eAAO,MAAM,iCAAiC;;;;;;iBAG5C,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;;;;;;iBAG3C,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;;;;;;;iBAGxC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;iBAGtC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAOlC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AACxF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAC1F,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,GAC1B,uBAAuB,GACvB,qBAAqB,CAAC"}

package/tools/execute.tool.d.ts

@@ -0,0 +1,6 @@
+import { ToolContext } from '@frontmcp/sdk';
+import { CodeCallExecuteResult, ExecuteToolInput } from './execute.schema';
+export default class ExecuteTool extends ToolContext {
+    execute(input: ExecuteToolInput): Promise<CodeCallExecuteResult>;
+}
+//# sourceMappingURL=execute.tool.d.ts.map

package/tools/execute.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.tool.d.ts","sourceRoot":"","sources":["../../src/tools/execute.tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,WAAW,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,qBAAqB,EAIrB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAqD1B,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,WAAW;IAC5C,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAwNvE"}

package/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { default as SearchTool } from './search.tool';
+export { default as DescribeTool } from './describe.tool';
+export { default as ExecuteTool } from './execute.tool';
+export { default as InvokeTool } from './invoke.tool';
+//# sourceMappingURL=index.d.ts.map

package/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC"}