@falai/agent 0.8.1 → 0.9.0-alpha-2

package/dist/cjs/src/core/SessionManager.d.ts

@@ -0,0 +1,86 @@
+/**
+ * SessionManager - Simplified session management with history
+ *
+ * Provides a clean, pragmatic API for managing sessions and conversation history
+ * in both server and client environments.
+ */
+import type { SessionState } from "../types/session";
+import type { History } from "../types/history";
+import { PersistenceManager } from "./PersistenceManager";
+import type { PersistenceAdapter } from "../types/persistence";
+/**
+ * SessionManager handles session lifecycle and conversation history
+ */
+export declare class SessionManager<TData = unknown> {
+    private currentSession?;
+    private persistenceManager?;
+    constructor(persistenceManagerOrAdapter?: PersistenceManager<TData> | PersistenceAdapter<TData>);
+    /**
+     * Core method: getOrCreate handles both existing and new sessions
+     * Works for sessionIds that exist, don't exist, or auto-generated IDs
+     */
+    getOrCreate(sessionId?: string): Promise<SessionState<TData>>;
+    /**
+     * Create a new session with optional custom ID
+     */
+    private create;
+    /**
+     * Add a message to the session history
+     */
+    addMessage(role: "user" | "assistant", content: string, name?: string): Promise<void>;
+    /**
+     * Get the current conversation history
+     */
+    getHistory(): History;
+    /**
+     * Set the entire conversation history
+     */
+    setHistory(history: History): void;
+    /**
+     * Clear all conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Save the current session to persistence
+     */
+    save(): Promise<void>;
+    /**
+     * Delete the current session from persistence
+     */
+    delete(): Promise<void>;
+    /**
+     * Get the current session
+     */
+    get current(): SessionState<TData> | undefined;
+    /**
+     * Get the current session ID
+     */
+    get id(): string | undefined;
+    /**
+     * Get agent-level collected data from the current session
+     */
+    getData(): Partial<TData>;
+    /**
+     * Set/merge agent-level data into the current session
+     * This updates the single source of truth for all collected data
+     */
+    setData(data: Partial<TData>): Promise<void>;
+    /**
+     * Update specific fields in the agent-level data
+     * Provides a more explicit method for data updates
+     */
+    updateData(updates: Partial<TData>): Promise<void>;
+    /**
+     * Clear all collected data while preserving session structure
+     */
+    clearData(): Promise<void>;
+    /**
+     * Reset the session (creates new session, optionally preserving history)
+     */
+    reset(preserveHistory?: boolean): Promise<SessionState<TData>>;
+    /**
+     * Get the persistence manager (for testing purposes)
+     */
+    getPersistenceManager(): PersistenceManager<TData> | undefined;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

package/dist/cjs/src/core/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../../../src/core/SessionManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;GAEG;AACH,qBAAa,cAAc,CAAC,KAAK,GAAG,OAAO;IACzC,OAAO,CAAC,cAAc,CAAC,CAAsB;IAC7C,OAAO,CAAC,kBAAkB,CAAC,CAA4B;gBAGrD,2BAA2B,CAAC,EACxB,kBAAkB,CAAC,KAAK,CAAC,GACzB,kBAAkB,CAAC,KAAK,CAAC;IAe/B;;;OAGG;IACG,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IA0BnE;;OAEG;YACW,MAAM;IA0BpB;;OAEG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,GAAG,WAAW,EAC1B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAoBhB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOlC;;OAEG;IACH,YAAY,IAAI,IAAI;IAOpB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B;;OAEG;IACH,IAAI,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS,CAE7C;IAED;;OAEG;IACH,IAAI,EAAE,IAAI,MAAM,GAAG,SAAS,CAE3B;IAED;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC;IAIzB;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBlD;;;OAGG;IACG,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAUhC;;OAEG;IACG,KAAK,CAAC,eAAe,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAqBlE;;OAEG;IACH,qBAAqB,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS;CAG/D"}

package/dist/cjs/src/core/SessionManager.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * SessionManager - Simplified session management with history
+ *
+ * Provides a clean, pragmatic API for managing sessions and conversation history
+ * in both server and client environments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+const PersistenceManager_1 = require("./PersistenceManager");
+/**
+ * SessionManager handles session lifecycle and conversation history
+ */
+class SessionManager {
+    constructor(persistenceManagerOrAdapter) {
+        if (persistenceManagerOrAdapter) {
+            // Check if it's a PersistenceManager or an adapter
+            if ("saveSessionState" in persistenceManagerOrAdapter) {
+                this.persistenceManager = persistenceManagerOrAdapter;
+            }
+            else {
+                // It's an adapter, create a PersistenceManager
+                this.persistenceManager = new PersistenceManager_1.PersistenceManager({
+                    adapter: persistenceManagerOrAdapter,
+                });
+            }
+        }
+    }
+    /**
+     * Core method: getOrCreate handles both existing and new sessions
+     * Works for sessionIds that exist, don't exist, or auto-generated IDs
+     */
+    async getOrCreate(sessionId) {
+        // If we already have a session and no sessionId specified, return it
+        if (this.currentSession && !sessionId) {
+            return this.currentSession;
+        }
+        // If sessionId provided, try to load it first
+        if (sessionId && this.persistenceManager) {
+            try {
+                const session = await this.persistenceManager.loadSessionState(sessionId);
+                if (session) {
+                    this.currentSession = session;
+                    return session;
+                }
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            }
+            catch (_error) {
+                // Session doesn't exist, will create new one with this ID
+            }
+        }
+        // Create new session (with provided ID or auto-generated)
+        return this.create(sessionId);
+    }
+    /**
+     * Create a new session with optional custom ID
+     */
+    async create(sessionId) {
+        const id = sessionId ||
+            `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        const session = {
+            id,
+            data: {}, // Agent-level data structure
+            routeHistory: [],
+            history: [], // Session manages its own history
+            metadata: {
+                createdAt: new Date(),
+                lastUpdatedAt: new Date(),
+            },
+        };
+        this.currentSession = session;
+        // Save to persistence if available
+        if (this.persistenceManager) {
+            await this.persistenceManager.saveSessionState(session.id, session);
+        }
+        return session;
+    }
+    /**
+     * Add a message to the session history
+     */
+    async addMessage(role, content, name) {
+        const session = await this.getOrCreate();
+        if (!session.history) {
+            session.history = [];
+        }
+        const historyItem = {
+            role,
+            content,
+            ...(name && { name }),
+        };
+        session.history.push(historyItem);
+        session.metadata.lastUpdatedAt = new Date();
+        // Auto-save to persistence
+        await this.save();
+    }
+    /**
+     * Get the current conversation history
+     */
+    getHistory() {
+        return this.currentSession?.history || [];
+    }
+    /**
+     * Set the entire conversation history
+     */
+    setHistory(history) {
+        if (this.currentSession) {
+            this.currentSession.history = history ? [...history] : [];
+            this.currentSession.metadata.lastUpdatedAt = new Date();
+        }
+    }
+    /**
+     * Clear all conversation history
+     */
+    clearHistory() {
+        if (this.currentSession) {
+            this.currentSession.history = [];
+            this.currentSession.metadata.lastUpdatedAt = new Date();
+        }
+    }
+    /**
+     * Save the current session to persistence
+     */
+    async save() {
+        if (this.currentSession && this.persistenceManager) {
+            await this.persistenceManager.saveSessionState(this.currentSession.id, this.currentSession);
+        }
+    }
+    /**
+     * Delete the current session from persistence
+     */
+    async delete() {
+        if (this.currentSession && this.persistenceManager) {
+            await this.persistenceManager.deleteSession(this.currentSession.id);
+            this.currentSession = undefined;
+        }
+    }
+    /**
+     * Get the current session
+     */
+    get current() {
+        return this.currentSession;
+    }
+    /**
+     * Get the current session ID
+     */
+    get id() {
+        return this.currentSession?.id;
+    }
+    /**
+     * Get agent-level collected data from the current session
+     */
+    getData() {
+        return this.currentSession?.data || {};
+    }
+    /**
+     * Set/merge agent-level data into the current session
+     * This updates the single source of truth for all collected data
+     */
+    async setData(data) {
+        // Ensure session exists
+        await this.getOrCreate();
+        if (this.currentSession && data) {
+            this.currentSession.data = {
+                ...this.currentSession.data,
+                ...data,
+            };
+            this.currentSession.metadata.lastUpdatedAt = new Date();
+            // Auto-save to persistence
+            await this.save();
+        }
+    }
+    /**
+     * Update specific fields in the agent-level data
+     * Provides a more explicit method for data updates
+     */
+    async updateData(updates) {
+        await this.setData(updates);
+    }
+    /**
+     * Clear all collected data while preserving session structure
+     */
+    async clearData() {
+        if (this.currentSession) {
+            this.currentSession.data = {};
+            this.currentSession.metadata.lastUpdatedAt = new Date();
+            // Auto-save to persistence
+            await this.save();
+        }
+    }
+    /**
+     * Reset the session (creates new session, optionally preserving history)
+     */
+    async reset(preserveHistory = false) {
+        const oldId = this.currentSession?.id;
+        const history = preserveHistory ? this.currentSession?.history : [];
+        // Create new session
+        const newSession = await this.create();
+        // Preserve history if requested
+        if (preserveHistory && history) {
+            newSession.history = [...history];
+        }
+        // Clean up old session from persistence
+        if (oldId && this.persistenceManager) {
+            await this.persistenceManager.deleteSession(oldId);
+        }
+        await this.save();
+        return newSession;
+    }
+    /**
+     * Get the persistence manager (for testing purposes)
+     */
+    getPersistenceManager() {
+        return this.persistenceManager;
+    }
+}
+exports.SessionManager = SessionManager;
+//# sourceMappingURL=SessionManager.js.map

package/dist/cjs/src/core/SessionManager.js.map

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

package/dist/cjs/src/core/Step.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Step in the route DSL
+ */
+import type { StepRef, StepOptions, StepResult, BranchSpec, BranchResult, Guideline, Tool } from "../types";
+import { Template } from "../types/template";
+/**
+ * Represents a step within a route
+ */
+export declare class Step<TContext = unknown, TData = unknown> {
+    readonly id: string;
+    private nextSteps;
+    private guidelines;
+    readonly routeId: string;
+    collect?: (keyof TData)[];
+    description?: string;
+    when?: Template<TContext, TData>;
+    skipIf?: (data: Partial<TData>) => boolean;
+    requires?: (keyof TData)[];
+    prompt?: Template<TContext, TData>;
+    prepare?: string | Tool<TContext, TData, unknown[], unknown> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    finalize?: string | Tool<TContext, TData, unknown[], unknown> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+    constructor(routeId: string, options?: StepOptions<TContext, TData>);
+    /**
+     * Configure the step properties after creation
+     * Useful for overriding initial step configuration
+     */
+    configure(config: {
+        description?: string;
+        collect?: (keyof TData)[];
+        skipIf?: (data: Partial<TData>) => boolean;
+        requires?: (keyof TData)[];
+        prompt?: Template<TContext, TData>;
+        prepare?: string | Tool<TContext, TData, unknown[], unknown> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+        finalize?: string | Tool<TContext, TData, unknown[], unknown> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+        tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+    }): this;
+    /**
+     * Shortcut to end the current route
+     *
+     * @param options - Optional step options for the end step
+     * @returns Terminal step result
+     */
+    endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>;
+    /**
+     * Create a transition from this step to another
+     *
+     * @param spec - Transition specification (prompt, tool, or direct step)
+     * @returns StepResult that supports chaining
+     */
+    nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>;
+    /**
+     * Create multiple branches from this step
+     *
+     * @param branches - Array of branch specifications
+     * @returns BranchResult mapping branch names to their step results
+     */
+    branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>;
+    /**
+     * Add a guideline specific to this step
+     */
+    addGuideline(guideline: Guideline<TContext>): void;
+    /**
+     * Get guidelines for this step
+     */
+    getGuidelines(): Guideline<TContext>[];
+    /**
+     * Get all transitions from this step
+     */
+    getTransitions(): Step<TContext, TData>[];
+    /**
+     * Check if this step should be skipped based on collected data
+     */
+    shouldSkip(data: Partial<TData>): boolean;
+    /**
+     * Check if this step has all required data to proceed
+     */
+    hasRequires(data: Partial<TData>): boolean;
+    /**
+     * Get step reference
+     */
+    getRef(): StepRef;
+    /**
+     * Create a step reference with nextStep capability for chaining
+     */
+    private createStepRefWithTransition;
+    /**
+     * Create a terminal step reference (for END_ROUTE)
+     */
+    private createTerminalRef;
+    /**
+     * Create a transition result for this step
+     */
+    asStepResult(): StepResult<TContext, TData>;
+}
+//# sourceMappingURL=Step.d.ts.map

package/dist/cjs/src/core/Step.d.ts.map

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

package/dist/cjs/src/core/Step.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Step in the route DSL
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Step = void 0;
+const constants_1 = require("../constants");
+const id_1 = require("../utils/id");
+/**
+ * Represents a step within a route
+ */
+class Step {
+    constructor(routeId, options = {}) {
+        this.nextSteps = [];
+        this.guidelines = [];
+        // Use provided ID or generate a deterministic one
+        this.id = options.id || (0, id_1.generateStepId)(routeId, options.description);
+        this.routeId = routeId;
+        this.description = options.description;
+        this.collect = options.collect;
+        this.skipIf = options.skipIf;
+        this.requires = options.requires;
+        this.prompt = options.prompt;
+        this.when = options.when;
+        this.prepare = options.prepare;
+        this.finalize = options.finalize;
+        this.tools = options.tools;
+    }
+    /**
+     * Configure the step properties after creation
+     * Useful for overriding initial step configuration
+     */
+    configure(config) {
+        if (config.description !== undefined) {
+            this.description = config.description;
+        }
+        if (config.collect !== undefined) {
+            this.collect = config.collect;
+        }
+        if (config.skipIf !== undefined) {
+            this.skipIf = config.skipIf;
+        }
+        if (config.requires !== undefined) {
+            this.requires = config.requires;
+        }
+        if (config.prompt !== undefined) {
+            this.prompt = config.prompt;
+        }
+        if (config.prepare !== undefined) {
+            this.prepare = config.prepare;
+        }
+        if (config.finalize !== undefined) {
+            this.finalize = config.finalize;
+        }
+        if (config.tools !== undefined) {
+            this.tools = config.tools;
+        }
+        return this;
+    }
+    /**
+     * Shortcut to end the current route
+     *
+     * @param options - Optional step options for the end step
+     * @returns Terminal step result
+     */
+    endRoute(options = {}) {
+        return this.nextStep({
+            ...options,
+            step: constants_1.END_ROUTE,
+        });
+    }
+    /**
+     * Create a transition from this step to another
+     *
+     * @param spec - Transition specification (prompt, tool, or direct step)
+     * @returns StepResult that supports chaining
+     */
+    nextStep(spec) {
+        // Handle END_ROUTE
+        if (spec.step && typeof spec.step === "symbol" && spec.step === constants_1.END_ROUTE) {
+            const endStep = new Step(this.routeId, {
+                ...spec,
+                id: constants_1.END_ROUTE_ID,
+            });
+            this.nextSteps.push(endStep);
+            return this.createTerminalRef();
+        }
+        // Handle direct step reference
+        if (spec.step && typeof spec.step !== "symbol") {
+            // This is a bit tricky. We need to find the actual Step instance.
+            // For now, let's assume the user will provide a Step instance directly.
+            // This part might need to be revisited.
+        }
+        // Create new target step for prompt or tool
+        const targetStep = new Step(this.routeId, spec);
+        this.nextSteps.push(targetStep);
+        return this.createStepRefWithTransition(targetStep.getRef(), targetStep);
+    }
+    /**
+     * Create multiple branches from this step
+     *
+     * @param branches - Array of branch specifications
+     * @returns BranchResult mapping branch names to their step results
+     */
+    branch(branches) {
+        const result = {};
+        for (const branchSpec of branches) {
+            // Create step options with optional ID
+            const stepOptions = branchSpec.id
+                ? { ...branchSpec.step, id: branchSpec.id }
+                : branchSpec.step;
+            // Create a new step for this branch
+            const branchStep = new Step(this.routeId, stepOptions);
+            // Add it to our transitions
+            this.nextSteps.push(branchStep);
+            // Create a step result for chaining
+            const branchName = branchSpec.name;
+            result[branchName] = this.createStepRefWithTransition(branchStep.getRef(), branchStep);
+        }
+        return result;
+    }
+    /**
+     * Add a guideline specific to this step
+     */
+    addGuideline(guideline) {
+        this.guidelines.push(guideline);
+    }
+    /**
+     * Get guidelines for this step
+     */
+    getGuidelines() {
+        return [...this.guidelines];
+    }
+    /**
+     * Get all transitions from this step
+     */
+    getTransitions() {
+        return [...this.nextSteps];
+    }
+    /**
+     * Check if this step should be skipped based on collected data
+     */
+    shouldSkip(data) {
+        if (!this.skipIf)
+            return false;
+        return this.skipIf(data);
+    }
+    /**
+     * Check if this step has all required data to proceed
+     */
+    hasRequires(data) {
+        if (!this.requires || this.requires.length === 0)
+            return true;
+        return this.requires.every((key) => data[key] !== undefined);
+    }
+    /**
+     * Get step reference
+     */
+    getRef() {
+        return {
+            id: this.id,
+            routeId: this.routeId,
+        };
+    }
+    /**
+     * Create a step reference with nextStep capability for chaining
+     */
+    createStepRefWithTransition(ref, step) {
+        const stepInstance = step || this;
+        return {
+            ...ref,
+            nextStep: (spec) => stepInstance.nextStep(spec),
+            branch: (branches) => stepInstance.branch(branches),
+        };
+    }
+    /**
+     * Create a terminal step reference (for END_ROUTE)
+     */
+    createTerminalRef() {
+        const terminalRef = {
+            id: constants_1.END_ROUTE_ID,
+            routeId: this.routeId,
+        };
+        return {
+            ...terminalRef,
+            nextStep: () => {
+                throw new Error("Cannot transition from END_ROUTE step");
+            },
+            branch: () => {
+                throw new Error("Cannot branch from END_ROUTE step");
+            },
+        };
+    }
+    /**
+     * Create a transition result for this step
+     */
+    asStepResult() {
+        return {
+            ...this.getRef(),
+            nextStep: (spec) => this.nextStep(spec),
+            branch: (branches) => this.branch(branches),
+        };
+    }
+}
+exports.Step = Step;
+//# sourceMappingURL=Step.js.map

package/dist/cjs/src/core/Step.js.map

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

package/dist/cjs/src/core/ToolExecutor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ToolExecutor - Simple utility for executing tools with context
+ *
+ * Tools execute BEFORE message generation to enrich context with data.
+ * The LLM sees the enriched context when generating responses.
+ */
+import type { Event, Tool } from "../types";
+export interface ToolExecutionResult {
+    toolName: string;
+    success: boolean;
+    data?: unknown;
+    contextUpdate?: Record<string, unknown>;
+    dataUpdate?: Record<string, unknown>;
+    error?: string;
+}
+export interface ExecuteToolParams<TContext = unknown, TData = unknown> {
+    tool: Tool<TContext, TData, unknown[], unknown>;
+    context: TContext;
+    updateContext: (updates: Partial<TContext>) => Promise<void>;
+    updateData: (updates: Partial<TData>) => Promise<void>;
+    history: Event[];
+    data?: Partial<TData>;
+    toolArguments?: Record<string, unknown>;
+}
+export interface ExecuteToolsParams<TContext = unknown, TData = unknown> {
+    tools: Array<Tool<TContext, TData, unknown[], unknown>>;
+    context: TContext;
+    updateContext: (updates: Partial<TContext>) => Promise<void>;
+    updateData: (updates: Partial<TData>) => Promise<void>;
+    history: Event[];
+    data?: Partial<TData>;
+}
+export declare class ToolExecutor<TContext = unknown, TData = unknown> {
+    /**
+     * Execute a single tool with context and collected data
+     * @param params - Execution parameters
+     */
+    executeTool(params: ExecuteToolParams<TContext, TData>): Promise<ToolExecutionResult>;
+    /**
+     * Execute multiple tools in sequence
+     * @param params - Execution parameters
+     */
+    executeTools(params: ExecuteToolsParams<TContext, TData>): Promise<ToolExecutionResult[]>;
+}
+//# sourceMappingURL=ToolExecutor.d.ts.map