@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/agent/tools2/tools/web-search.js

@@ -0,0 +1,210 @@
+/**
+ * Web Search Tool
+ *
+ * Searches the web using DuckDuckGo's HTML search.
+ * Supports filtering by allowed/blocked domains.
+ */
+import * as cheerio from "cheerio";
+import { z } from "zod";
+import { getErrorMeta, getLogger } from "../../../../util/logger.js";
+import { createToolFactory, PermissionLevel, ToolCategory } from "../types.js";
+/**
+ * Headers to mimic a browser request.
+ */
+const BROWSER_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Accept-Encoding": "gzip, deflate, br",
+    "Cache-Control": "no-cache",
+    Pragma: "no-cache",
+    "Sec-Ch-Ua": '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+    "Sec-Ch-Ua-Mobile": "?0",
+    "Sec-Ch-Ua-Platform": '"macOS"',
+    "Sec-Fetch-Dest": "document",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-Site": "none",
+    "Sec-Fetch-User": "?1",
+    "Upgrade-Insecure-Requests": "1",
+};
+/**
+ * Extracts the actual URL from a DuckDuckGo redirect URL.
+ *
+ * DuckDuckGo wraps URLs in their redirect format like:
+ * //duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com&rut=...
+ *
+ * @param ddgUrl - The DuckDuckGo redirect URL
+ * @returns The actual destination URL, or the original URL if parsing fails
+ */
+function extractUrlFromDdgRedirect(ddgUrl) {
+    try {
+        // Handle relative URLs starting with //
+        const fullUrl = ddgUrl.startsWith("//") ? `https:${ddgUrl}` : ddgUrl;
+        const url = new URL(fullUrl);
+        const uddg = url.searchParams.get("uddg");
+        if (uddg) {
+            return decodeURIComponent(uddg);
+        }
+        return ddgUrl;
+    }
+    catch (error) {
+        getLogger().debug("Failed to parse DDG redirect URL", { ddgUrl, error });
+        return ddgUrl;
+    }
+}
+/**
+ * Parses DuckDuckGo HTML search results and extracts search results.
+ *
+ * @param html - The HTML content from DuckDuckGo search
+ * @returns Array of search results
+ */
+function parseDuckDuckGoResults(html) {
+    const $ = cheerio.load(html);
+    const results = [];
+    // DuckDuckGo results are in div.result elements
+    // Each result has:
+    // - h2.result__title containing a.result__a (title and link)
+    // - a.result__snippet (description)
+    $("div.result").each((_index, element) => {
+        const $el = $(element);
+        // Skip ads (they have badge--ad class)
+        if ($el.find(".badge--ad").length > 0) {
+            return;
+        }
+        // Find the title link
+        const $titleLink = $el.find("h2.result__title a.result__a").first();
+        const title = $titleLink.text().trim();
+        const rawLink = $titleLink.attr("href") || "";
+        // Extract the actual URL from DuckDuckGo's redirect
+        const link = extractUrlFromDdgRedirect(rawLink);
+        // Find the snippet
+        const snippet = $el.find("a.result__snippet").first().text().trim();
+        // Only add valid results
+        if (title && link && link.startsWith("http")) {
+            results.push({ title, link, snippet });
+        }
+    });
+    return results;
+}
+/**
+ * Filters results by allowed and blocked domains.
+ *
+ * @param results - Array of search results
+ * @param allowedDomains - Only include results from these domains (if provided)
+ * @param blockedDomains - Exclude results from these domains
+ * @returns Filtered results
+ */
+function filterByDomains(results, allowedDomains, blockedDomains) {
+    return results.filter((result) => {
+        try {
+            const domain = new URL(result.link).hostname.toLowerCase();
+            // Check blocked domains first
+            if (blockedDomains?.length) {
+                const isBlocked = blockedDomains.some((blocked) => domain.includes(blocked.toLowerCase()));
+                if (isBlocked)
+                    return false;
+            }
+            // Check allowed domains (if specified)
+            if (allowedDomains?.length) {
+                const isAllowed = allowedDomains.some((allowed) => domain.includes(allowed.toLowerCase()));
+                if (!isAllowed)
+                    return false;
+            }
+            return true;
+        }
+        catch {
+            // Invalid URL, exclude it
+            return false;
+        }
+    });
+}
+/**
+ * Web search tool factory.
+ *
+ * Searches the web using DuckDuckGo's HTML search.
+ */
+export const webSearchToolFactory = createToolFactory("web_search", () => ({
+    description: `
+Searches the web and returns results. Use this tool PROACTIVELY when the user's question likely requires current information.
+
+WHEN TO USE (proactively search when):
+- User asks about current versions, releases, or "latest" anything
+- User asks about recent changes, updates, or deprecations
+- User asks about best practices or recommendations (these evolve)
+- You're uncertain about specific library APIs, syntax, or features
+- User asks to compare tools or libraries
+- Troubleshooting errors or issues that may have known solutions
+- You just installed a new library - ALWAYS search for its docs before using it
+- Any question where your training data might be outdated
+
+DO NOT wait for the user to explicitly ask you to search - if the question benefits from current information, search first.
+
+Usage:
+- Provide a search query to find relevant web pages
+- Optionally filter results by allowed or blocked domains
+- Returns titles, links, and snippets for each result
+
+Parameters:
+- query: The search query (required, min 2 characters)
+- allowed_domains: Only include results from these domains
+- blocked_domains: Exclude results from these domains
+
+Examples:
+- Basic search: query="react hooks tutorial"
+- Filter by domain: query="typescript generics", allowed_domains=["developer.mozilla.org", "typescriptlang.org"]
+- Exclude domains: query="python async", blocked_domains=["w3schools.com"]
+`,
+    category: ToolCategory.GENERAL,
+    defaultPermission: PermissionLevel.ALLOW,
+    readOnly: true,
+    inputSchema: z.object({
+        query: z.string().min(2).describe("The search query"),
+        allowed_domains: z
+            .array(z.string())
+            .optional()
+            .describe("Only include results from these domains"),
+        blocked_domains: z
+            .array(z.string())
+            .optional()
+            .describe("Exclude results from these domains"),
+    }),
+    execute: async ({ query, allowed_domains, blocked_domains }, options) => {
+        try {
+            // Use DuckDuckGo HTML search (works without JavaScript)
+            const searchUrl = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+            // Fetch search results
+            const response = await fetch(searchUrl, {
+                headers: {
+                    ...BROWSER_HEADERS,
+                    Referer: "https://html.duckduckgo.com/",
+                },
+                redirect: "follow",
+                signal: options?.abortSignal,
+            });
+            if (!response.ok) {
+                throw new Error(`Search returned status ${response.status}`);
+            }
+            const html = await response.text();
+            // Parse results
+            let results = parseDuckDuckGoResults(html);
+            // Filter by domains
+            results = filterByDomains(results, allowed_domains, blocked_domains);
+            return { results };
+        }
+        catch (error) {
+            getLogger().error("Web search failed", getErrorMeta({ query, error }));
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error("Web search was aborted");
+            }
+            if (error instanceof Error) {
+                throw new Error(`Failed to search: ${error.message}`);
+            }
+            throw new Error("Failed to search: Unknown error");
+        }
+    },
+    getSummary: (input, output) => ({
+        input: `query: "${input.query}"`,
+        output: `Found ${output.results.length} result${output.results.length === 1 ? "" : "s"}`,
+    }),
+}));
+//# sourceMappingURL=web-search.js.map

package/dist/ai-service/agent/tools2/tools/web-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/web-search.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/agent/tools2/tools/write.d.ts

@@ -0,0 +1,14 @@
+import type { AppShell } from "../../../app-interface/shell.js";
+/**
+ * Write tool - Writes files to the filesystem.
+ */
+export declare const writeToolFactory: import("../types.js").ToolFactory<{
+    appShell: AppShell;
+}, import("../types.js").Tool<{
+    content: string;
+    file_path: string;
+}, {
+    success: boolean;
+    message: string;
+}>>;
+//# sourceMappingURL=write.d.ts.map

package/dist/ai-service/agent/tools2/tools/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAGhE;;GAEG;AACH,eAAO,MAAM,gBAAgB;cAEJ,QAAQ;;;;;;;GA0BhC,CAAC"}

package/dist/ai-service/agent/tools2/tools/write.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { createToolFactory, PermissionLevel, ToolCategory } from "../types.js";
+/**
+ * Write tool - Writes files to the filesystem.
+ */
+export const writeToolFactory = createToolFactory("write", (services) => ({
+    description: "Writes a file to the local filesystem.",
+    category: ToolCategory.FILE,
+    defaultPermission: PermissionLevel.PROMPT,
+    inputSchema: z.object({
+        file_path: z.string().describe("Relative path to file"),
+        content: z.string().describe("Content to write"),
+    }),
+    execute: async ({ file_path, content }) => {
+        try {
+            await services.appShell.writeFile(file_path, content);
+            return { success: true, message: `File written: ${file_path}` };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to write file: ${error.message}`);
+            }
+            throw new Error("Failed to write file: Unknown error");
+        }
+    },
+    getSummary: (input) => {
+        const lineCount = input.content.split("\n").length;
+        return {
+            output: `Wrote ${lineCount} line${lineCount === 1 ? "" : "s"}`,
+        };
+    },
+}));
+//# sourceMappingURL=write.js.map

package/dist/ai-service/agent/tools2/tools/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAC/C,OAAO,EACP,CAAC,QAAgC,EAAE,EAAE,CAAC,CAAC;IACrC,WAAW,EAAE,wCAAwC;IACrD,QAAQ,EAAE,YAAY,CAAC,IAAI;IAC3B,iBAAiB,EAAE,eAAe,CAAC,MAAM;IACzC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACvD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;KACjD,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE;QACxC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACtD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,SAAS,EAAE,EAAE,CAAC;QAClE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IACD,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;QACpB,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACnD,OAAO;YACL,MAAM,EAAE,SAAS,SAAS,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;SAC/D,CAAC;IACJ,CAAC;CACF,CAAC,CACH,CAAC"}

package/dist/ai-service/agent/tools2/types.d.ts

@@ -0,0 +1,396 @@
+import type { tool } from "@ai-sdk/provider-utils";
+import type { ToolExecutionOptions } from "ai";
+import type z from "zod";
+import type { AiMode, AiEntityType, PlanContext, PromptContextEntity, PromptContextIntegration, AiToolPermission, AiToolExecutionErrorCode } from "@superblocksteam/library-shared/types";
+import type { CompactionSummary } from "../../llm/context-v2/types.js";
+import type { SubagentType } from "../subagents/types.js";
+/**
+ * Tool categories for grouping and middleware selection.
+ */
+export declare enum ToolCategory {
+    FILE = "file",
+    COMPONENT = "component",
+    MULTI_FILE = "multi_file",
+    GENERAL = "general",
+    API = "api",
+    SUBAGENT = "subagent",
+    METADATA = "metadata",
+    DATA = "data",
+    MEMORY = "memory",
+    PLAN = "plan",
+    TEST = "test",
+    DEBUG = "debug",
+    GIT = "git",
+    /**
+     * Tools that manipulate UI state interactively.
+     *
+     * Used for tools that:
+     * - Manipulate UI state (Redux, form fields, tabs)
+     * - Require the user to be looking at the screen (they see what's happening)
+     *
+     * Combine with PermissionLevel.ALLOW or PermissionLevel.PROMPT to control
+     * whether Clark executes immediately or asks for confirmation first.
+     * e.g. filling a field (ALLOW) vs saving integration changes (PROMPT).
+     */
+    INTERACTIVE = "interactive"
+}
+/**
+ * Entity reference extracted from tool input.
+ *
+ * Represents an entity (integration, file, etc.) that the tool
+ * will access, requiring user approval.
+ */
+export interface EntityReference {
+    /** Type of entity being accessed */
+    type: AiEntityType;
+    /** Unique identifier of the entity */
+    id: string;
+}
+type ToolParams<Input, Output> = Parameters<typeof tool<Input, Output>>[0];
+/**
+ * Core tool interface.
+ *
+ * A tool is a unit of functionality that can be invoked with validated input
+ * and returns validated output. Tools are registered in the registry and can
+ * be executed with access control.
+ */
+export interface Tool<Input = any, Output = any> {
+    /** Unique tool name */
+    name: string;
+    /** Human-readable description for LLM */
+    description: string;
+    /** Category for grouping tools */
+    category: ToolCategory;
+    /** Default permission level (can be overridden by rules) */
+    defaultPermission?: PermissionLevel;
+    /** Whether the tool is read-only (default: false) */
+    readOnly?: boolean;
+    /** Maximum execution time in milliseconds. Defaults to 60 seconds. */
+    timeoutMs?: number;
+    /** Whether unapproved Plan mode may call this tool despite it not being read-only. */
+    availableInPlanModeWithoutApproval?: boolean;
+    /**
+     * Optional function to determine whether to skip output size limiting for this tool.
+     * Receives the output from execute() and returns true to skip the limit check.
+     * Useful for tools that output content type with media parts (e.g., screenshots),
+     * as media parts are handled separately by the AI SDK and don't contribute to token count
+     * in the same way as text/JSON outputs.
+     */
+    skipOutputLimit?: (output: Output) => boolean;
+    /** Zod schema for input validation */
+    inputSchema: z.ZodType<Input>;
+    /** Optional Zod schema for output validation */
+    outputSchema?: z.ZodType<Output>;
+    /**
+     * Optional hook invoked immediately when the tool is called, before
+     * permission checks and after input validation.
+     *
+     * Use this to perform side effects such as updating internal state
+     * (e.g., clark context) as soon as a tool call arrives from the LLM.
+     *
+     * Throwing an error aborts execution — the registry catches it and
+     * returns a `ToolExecutionError` to the LLM. Returning (or resolving)
+     * normally allows execution to continue through the regular flow.
+     *
+     * @param input - Input from the LLM
+     * @param options - Tool call options (toolCallId, messages, etc.)
+     *
+     * @example
+     * onCall: (input) => {
+     *   clark.updateContext({ lastToolCall: toolName });
+     *   if (someCondition) throw new Error("Cannot call this tool right now");
+     * }
+     */
+    onCall?: (input: Input, options?: ToolExecutionOptions) => void | Promise<void>;
+    /** Execute the tool with validated input */
+    execute: (input: Input, options: ToolExecutionOptions) => Promise<Output>;
+    /**
+     * Optional conversion function that maps the tool result to an output
+     * that can be used by the language model.
+     */
+    toModelOutput?: ToolParams<Input, Output>["toModelOutput"];
+    /**
+     * Optional function to get the required permissions for the tool.
+     *
+     * @param input - Validated tool input
+     * @returns Array of required permissions
+     *
+     * @example
+     * getRequiredPermissions: (input) => [{
+     *   entityType: AiEntityType.PAGE,
+     *   entityId: input.filePath,
+     *   permissionType: AiPermissionType.DELETE,
+     * }]
+     */
+    getRequiredPermissions?: (input: Input) => Promise<AiToolPermission[]> | AiToolPermission[];
+    /**
+     * Optional function to get action name in different tenses.
+     *
+     * Used for displaying the tool action in messages before, during, and after
+     * execution. Enables context-aware messaging without hardcoding tool names.
+     * When input is provided, may return operation-specific action names.
+     *
+     * @param input - Optional validated tool input (e.g. when used in permission prompt)
+     * @returns Action name in future, present, and past tense
+     *
+     * @example
+     * getActionName: () => ({
+     *   future: "execute SQL query",
+     *   present: "executing SQL query",
+     *   past: "executed SQL query"
+     * })
+     * @example
+     * getActionName: (input) => input?.operation === 'commit' ? { future: "commit changes", ... } : { future: "run git", ... }
+     */
+    getActionName?: (input?: Input) => {
+        future: string;
+        present: string;
+        past: string;
+    };
+    /**
+     * Optional function to format tool input for human-readable display.
+     *
+     * Returns the target entities/resources being acted upon and optional details.
+     * Used in prompts and messages to show the user what will be affected.
+     * The action itself comes from getActionName(), so focus on the targets.
+     *
+     * @param input - Validated tool input
+     * @returns Formatted input with targets array and optional details
+     *
+     * @example
+     * formatInput: (input) => ({
+     *   targets: [integrationName],
+     *   details: input.params.query
+     * })
+     */
+    formatInput?: (input: Input) => {
+        targets: string[];
+        details?: string;
+        summary?: string;
+    } | Promise<{
+        targets: string[];
+        details?: string;
+        summary?: string;
+    }>;
+    /**
+     * Optional function to generate summaries for the tool's input and output.
+     *
+     * Used during context compaction to provide meaningful summaries instead of
+     * generic placeholders. Outputs are always compacted with summaries, while
+     * inputs are only compacted when they exceed a size threshold.
+     *
+     * IMPORTANT: This function receives the original typed output, NOT the
+     * potentially truncated string from outputLimiter. The middleware ordering
+     * in tools.ts ensures summaryInjector runs BEFORE outputLimiter, so you
+     * can safely access all properties on the output object.
+     *
+     * @param input - The validated tool input
+     * @param output - The tool's original output (always the typed Output, never truncated)
+     * @returns Separate summaries for input and output
+     *
+     * @example
+     * getSummary: (input, output) => ({
+     *   input: `pattern: "${input.pattern}"`,
+     *   output: `Found ${output.matches} matches`
+     * })
+     */
+    getSummary?: (input: Input, output: Output) => CompactionSummary;
+}
+/**
+ * Permission levels for tool execution.
+ */
+export declare enum PermissionLevel {
+    /** Execute immediately without user interaction */
+    ALLOW = "allow",
+    /** Prompt user for confirmation before execution */
+    PROMPT = "prompt",
+    /** Block execution completely */
+    BLOCK = "block"
+}
+/**
+ * Factory for creating tool instances.
+ *
+ * Allows tools to be registered before their dependencies are available,
+ * then instantiated with dependencies at runtime.
+ */
+export interface ToolFactory<TDeps = any, T extends Tool = Tool> {
+    /** Tool name for registration lookup */
+    name: string;
+    /** Factory function that creates a tool instance */
+    create: (deps: TDeps) => T;
+}
+/**
+ * Helper function to create a tool factory without name duplication.
+ *
+ * The name is defined once and automatically injected into the tool,
+ * eliminating the need to repeat it in the tool definition.
+ *
+ * Provides full type inference from Zod schemas - input and output types
+ * are automatically inferred from inputSchema and outputSchema.
+ *
+ * @param name - Unique tool name
+ * @param factory - Factory function that receives dependencies and returns a tool (without name)
+ * @returns Tool factory with full type inference
+ *
+ * @example
+ * const myTool = createToolFactory('my-tool', (deps) => ({
+ *   description: 'Does something',
+ *   category: 'utilities',
+ *   inputSchema: z.object({ count: z.number() }),
+ *   outputSchema: z.object({ result: z.string() }),
+ *   execute: async (input) => {
+ *     // input is typed as { count: number }
+ *     // return type must be { result: string }
+ *     return { result: String(input.count) };
+ *   }
+ * }));
+ */
+export declare function createToolFactory<TInputSchema extends z.ZodTypeAny, TDeps, TOutputSchema extends z.ZodTypeAny | undefined = undefined, TInput = z.input<TInputSchema>, TOutput = TOutputSchema extends z.ZodTypeAny ? z.infer<TOutputSchema> : any>(name: string, factory: (deps: TDeps) => {
+    description: string;
+    category: ToolCategory;
+    defaultPermission?: PermissionLevel;
+    readOnly?: boolean;
+    timeoutMs?: number;
+    availableInPlanModeWithoutApproval?: boolean;
+    skipOutputLimit?: (output: TOutput) => boolean;
+    inputSchema: TInputSchema;
+    outputSchema?: TOutputSchema;
+    onCall?: (input: TInput, options?: ToolExecutionOptions) => void | Promise<void>;
+    execute: (input: TInput, options: ToolExecutionOptions) => Promise<TOutput>;
+    toModelOutput?: ToolParams<TInput, TOutput>["toModelOutput"];
+    getRequiredPermissions?: (input: TInput) => Promise<AiToolPermission[]> | AiToolPermission[];
+    getActionName?: (input?: TInput) => {
+        future: string;
+        present: string;
+        past: string;
+    };
+    formatInput?: (input: TInput) => {
+        targets: string[];
+        details?: string;
+        summary?: string;
+    } | Promise<{
+        targets: string[];
+        details?: string;
+        summary?: string;
+    }>;
+    getSummary?: (input: TInput, output: TOutput) => CompactionSummary;
+}): ToolFactory<TDeps, Tool<TInput, TOutput>>;
+/**
+ * Context passed to access control rules.
+ *
+ * Contains information about the execution environment, user, session, etc.
+ */
+export interface AccessControlContext {
+    /** Subagent */
+    subagent?: SubagentType;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** User role */
+    userRole?: string;
+    /** Current AI mode (undefined defaults to BUILD) */
+    mode?: AiMode;
+    /** Detailed plan context information */
+    planContext?: PlanContext;
+    /** Integrations explicitly tagged or selected by the user */
+    availableIntegrations?: PromptContextIntegration[];
+    /** Entities explicitly tagged by the user in the prompt */
+    taggedEntities?: PromptContextEntity[];
+    /** Whether read access permission prompts are enabled for Clark AI */
+    enableClarkAiReadAccessPermission?: boolean;
+    /** Additional context properties */
+    [key: string]: any;
+}
+/**
+ * Access control rule function.
+ *
+ * Returns the permission level for a tool execution.
+ * Rules are evaluated in order, most restrictive wins.
+ */
+export type AccessControlRule = (tool: Tool, context: AccessControlContext, input?: any) => PermissionLevel | Promise<PermissionLevel>;
+/**
+ * Handler for prompting user for confirmation.
+ *
+ * Called when a tool requires user approval before execution.
+ * Should show a confirmation dialog and return user's decision.
+ *
+ * The handler receives the complete tool object, allowing access to:
+ * - tool.name, tool.description, tool.category for context
+ * - tool.getActionName() for tense-based display (if defined)
+ * - tool.formatInput(input) for human-readable input summary (if defined)
+ * - tool.getRequiredPermissions(input) to see what entities will be accessed (if defined)
+ *
+ * Returns:
+ * - ALLOW: Execute once, don't store permission
+ * - ALWAYS_ALLOW: Execute and store permission for future use (with alwaysAllowPermissions indicating which specific permissions to store)
+ * - DENY: Block execution
+ */
+export type PromptHandler = (tool: Tool, input: any, permissions: AiToolPermission[], context: AccessControlContext, options?: ToolExecutionOptions) => Promise<void>;
+/**
+ * Middleware function that can transform tools.
+ * Receives the tool name and tool instance, returns transformed tool.
+ */
+export type ToolMiddleware = (tool: Tool) => Tool;
+/**
+ * Result of tool execution.
+ */
+export type ToolExecutionResult<Output = any> = ToolExecutionSuccessResult<Output> | ToolExecutionErrorResult;
+export type ToolExecutionSuccessResult<Output = any> = {
+    type: "success";
+    data: Output;
+};
+export type ToolExecutionErrorResult = {
+    type: "error";
+    error: ToolExecutionError;
+};
+/**
+ * Severity level for tool execution errors.
+ * Used to determine the appropriate log level.
+ */
+export type ToolExecutionErrorSeverity = "info" | "warn" | "error";
+export interface ToolExecutionErrorOptions {
+    toolName: string;
+    input: any;
+    context: AccessControlContext;
+    cause?: unknown;
+    code?: AiToolExecutionErrorCode;
+    /** Severity level for logging. Defaults to "error" if not specified. */
+    severity?: ToolExecutionErrorSeverity;
+}
+export declare class ToolExecutionError extends Error {
+    readonly name: string;
+    readonly options?: ToolExecutionErrorOptions;
+    private _message?;
+    constructor(message: string, options?: ToolExecutionErrorOptions);
+    constructor(options?: ToolExecutionErrorOptions);
+    private getMessage;
+    /**
+     * Returns only the descriptive error text from this error and its cause chain,
+     * without serialized input/context. Used to prevent duplication when this error
+     * is nested as a cause of another ToolExecutionError.
+     */
+    private getErrorText;
+    get code(): AiToolExecutionErrorCode | undefined;
+    get toolName(): string | undefined;
+    get severity(): ToolExecutionErrorSeverity;
+    get input(): any;
+    get message(): string;
+    get stack(): string | undefined;
+    get cause(): unknown;
+    /**
+     * Custom JSON serialization to ensure the message getter is included.
+     * This is necessary because JSON.stringify doesn't serialize getters by default.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        toolName: string | undefined;
+        input: any;
+        severity: ToolExecutionErrorSeverity;
+        cause: unknown;
+        stack: string | undefined;
+    };
+}
+export {};
+//# sourceMappingURL=types.d.ts.map