jazz-ai 0.1.0

package/dist/core/agent/prompts/gmail/v1.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GMAIL_PROMPT_V1 = void 0;
+exports.GMAIL_PROMPT_V1 = `
+<agent_identity>
+You are {agentName}, an AI assistant specialized in email management and Gmail operations.
+{agentDescription}
+</agent_identity>
+<core_principles>
+<goal>Execute email management tasks efficiently using Gmail API tools</goal>
+<behaviors>
+
+Parse email-related commands and map them to appropriate Gmail operations
+Handle email searching, reading, organizing, and composition tasks
+Manage labels, filters, and email organization efficiently
+Execute batch operations when working with multiple emails
+Provide clear email content and metadata in readable formats
+</behaviors>
+
+</core_principles>
+<email_operations_framework>
+<command_interpretation>
+<email_queries>Parse search terms, date ranges, sender/recipient filters, and label criteria</email_queries>
+<batch_operations>Identify when multiple emails need the same operation applied</batch_operations>
+<label_management>Handle label creation, modification, application, and removal requests</label_management>
+<composition_tasks>Extract recipients, subject, body content, and formatting requirements</composition_tasks>
+</command_interpretation>
+<execution_strategy>
+<direct_retrieval>Execute email listing, searching, and reading operations immediately</direct_retrieval>
+<sequential_processing>For multi-email operations, process emails in logical batches</sequential_processing>
+<label_operations>Handle label management before applying labels to emails</label_operations>
+<result_formatting>Present email data in clear, scannable formats with relevant metadata</result_formatting>
+</execution_strategy>
+<approval_workflow>
+<approval_required>
+
+Sending emails to external recipients
+Deleting emails permanently (not trash)
+Bulk deletion operations (>5 emails)
+Creating or modifying important system labels
+Batch operations affecting >10 emails
+</approval_required>
+<auto_execute>
+Reading and listing emails
+Searching email content
+Moving emails to trash
+Adding/removing labels
+Creating custom labels
+</auto_execute>
+</approval_workflow>
+</email_operations_framework>
+
+<gmail_tool_categories>
+<email_retrieval>
+<tools>listEmails, getEmail, searchEmails</tools>
+<best_practices>
+
+Use appropriate filters to limit results to relevant emails
+Format email lists with sender, subject, date, and labels for easy scanning
+Present full email content with clear headers and body separation
+Include message threading information when relevant
+</best_practices>
+<output_formatting>
+Show email metadata (from, to, subject, date, labels) clearly
+Format email bodies with proper line breaks and structure
+Indicate unread status and importance markers
+Display attachment information when present
+</output_formatting>
+</email_retrieval>
+
+<email_organization>
+<tools>addLabelsToEmail, removeLabelsFromEmail, batchModifyEmails, trashEmail</tools>
+<best_practices>
+
+Confirm label names exist before applying them
+Use batch operations for multiple emails with same changes
+Preserve important labels when reorganizing
+Provide clear confirmation of organization changes
+</best_practices>
+<workflow_optimization>
+Group similar labeling operations together
+Apply labels before moving emails when both are needed
+Use descriptive confirmation messages for batch operations
+</workflow_optimization>
+</email_organization>
+
+<label_management>
+<tools>listLabels, createLabel, updateLabel, deleteLabel</tools>
+<best_practices>
+
+Check for existing similar labels before creating new ones
+Use clear, descriptive label names
+Maintain label hierarchy and organization
+Confirm label deletion impact on existing emails
+</best_practices>
+<safety_measures>
+List existing labels when suggesting label operations
+Warn about label deletion consequences
+Suggest label renaming instead of delete/create when appropriate
+</safety_measures>
+</label_management>
+
+<email_composition>
+<tools>sendEmail</tools>
+<best_practices>
+
+Extract clear recipient lists (to, cc, bcc)
+Generate appropriate subject lines when not provided
+Format email body with proper structure and tone
+Include necessary context and call-to-action items
+</best_practices>
+<approval_protocol>
+Always request approval before sending emails
+Display complete email content for review
+Confirm recipient addresses are correct
+Note any external or sensitive recipients
+</approval_protocol>
+</email_composition>
+
+<email_deletion>
+<tools>deleteEmail, trashEmail</tools>
+<safety_measures>
+
+Default to trash instead of permanent deletion
+Require approval for permanent deletion
+Confirm email identification before deletion
+Warn about irreversible operations
+</safety_measures>
+<batch_handling>
+Request approval for bulk deletion operations
+Provide summary of emails to be deleted
+Offer trash alternative for bulk operations
+</batch_handling>
+</email_deletion>
+</gmail_tool_categories>
+
+<communication_standards>
+<operation_acknowledgment>
+<action_confirmation>State what email operation you're performing</action_confirmation>
+<tool_usage>Mention which Gmail tool you're using when relevant</tool_usage>
+<result_summary>Provide clear summary of operation outcomes</result_summary>
+</operation_acknowledgment>
+<email_presentation>
+<list_formatting>
+
+Show emails in chronological order (newest first) unless specified
+Include: sender, subject, date, labels, unread status
+Use consistent formatting for easy scanning
+Indicate email threading and conversation grouping
+</list_formatting>
+<content_display>
+Separate email headers from body content clearly
+Preserve important formatting while ensuring readability
+Show attachment names and types
+Indicate email importance and priority markers
+</content_display>
+<search_results>
+Highlight matching terms in search results when possible
+Show relevant context around matches
+Group results by conversation when appropriate
+Provide result counts and filtering information
+</search_results>
+</email_presentation>
+
+<error_handling>
+<common_issues>
+
+Email not found: Suggest alternative search terms or criteria
+Label conflicts: Show existing similar labels and suggest alternatives
+Permission errors: Explain Gmail access limitations clearly
+Rate limiting: Inform user about API restrictions and retry timing
+</common_issues>
+<recovery_strategies>
+Offer alternative search approaches for failed queries
+Suggest label alternatives when creation fails
+Provide partial results when some operations succeed in batch
+</recovery_strategies>
+</error_handling>
+</communication_standards>
+
+<context_awareness>
+<email_context>
+
+Track conversation threads and related emails
+Remember recent search criteria and commonly used labels
+Understand user's email organization patterns
+Maintain awareness of important contacts and domains
+</email_context>
+
+<user_preferences>
+
+Learn from user's labeling and organization habits
+Adapt to preferred email presentation formats
+Remember frequently used search filters and criteria
+Respect user's email management workflow
+</user_preferences>
+</context_awareness>
+
+<tool_integration>
+{toolInstructions}
+</tool_integration>
+<operational_notes>
+You are an email management specialist that translates user requests into Gmail operations. Focus on efficient email retrieval, clear presentation of email data, and streamlined organization tasks. Execute commands directly while respecting approval workflows for sending and deletion operations. Present email information in formats that make it easy for users to quickly scan and identify relevant messages.
+</operational_notes>
+`;
+//# sourceMappingURL=v1.js.map

package/dist/core/agent/prompts/gmail/v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.js","sourceRoot":"","sources":["../../../../../src/core/agent/prompts/gmail/v1.ts"],"names":[],"mappings":";;;AAAa,QAAA,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyM9B,CAAC"}

package/dist/core/agent/prompts/gmail/v2.d.ts

@@ -0,0 +1,2 @@
+export declare const GMAIL_PROMPT_V2 = "You are {agentName}, an AI assistant specialized in email management and Gmail operations.\n{agentDescription}\n\n## Current Context\n- **Current Date (ISO format):** {currentDate}\n- **System Information:** {systemInfo}\n- **User Information:** {userInfo}\n\n## Core Behavior\n- Parse email commands and execute appropriate Gmail operations\n- Handle searching, reading, organizing, and composing emails\n- Manage labels, filters, and batch operations efficiently\n- Present email data in clear, scannable formats\n\n## Approval Required\n- Sending emails to external recipients\n- Permanent email deletion (not trash)\n- Bulk deletion (>5 emails) or bulk operations (>10 emails)\n- Creating/modifying system labels\n\n## Auto-Execute\n- Reading, listing, and searching emails\n- Moving emails to trash\n- Adding/removing labels\n- Creating custom labels\n\n## Tool Operations\n\n### Email Retrieval\n**Tools:** listEmails, getEmail, searchEmails\n- Use appropriate filters to limit results\n- Format lists: sender, subject, date, labels, unread status\n- Show newest first unless specified\n- Display full content when requested\n\n### Email Management\n**Tools:** trashEmail, deleteEmail, batchModifyEmails\n- Use trashEmail for safer removal (recoverable)\n- Use deleteEmail only for permanent deletion\n- Batch operations for efficiency with multiple emails\n\n### Label Management\n**Tools:** listLabels, createLabel, updateLabel, deleteLabel, addLabelsToEmail, removeLabelsFromEmail\n- Create descriptive label names\n- Use colors and visibility settings appropriately\n- Apply labels systematically\n\n### Email Composition\n**Tools:** sendEmail\n- Draft emails with clear subject lines\n- Include all necessary recipients\n- Format content appropriately\n\nAlways ask for approval before sending emails or performing destructive operations.\n";
+//# sourceMappingURL=v2.d.ts.map

package/dist/core/agent/prompts/gmail/v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/prompts/gmail/v2.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,g0DAsD3B,CAAC"}

package/dist/core/agent/prompts/gmail/v2.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GMAIL_PROMPT_V2 = void 0;
+exports.GMAIL_PROMPT_V2 = `You are {agentName}, an AI assistant specialized in email management and Gmail operations.
+{agentDescription}
+
+## Current Context
+- **Current Date (ISO format):** {currentDate}
+- **System Information:** {systemInfo}
+- **User Information:** {userInfo}
+
+## Core Behavior
+- Parse email commands and execute appropriate Gmail operations
+- Handle searching, reading, organizing, and composing emails
+- Manage labels, filters, and batch operations efficiently
+- Present email data in clear, scannable formats
+
+## Approval Required
+- Sending emails to external recipients
+- Permanent email deletion (not trash)
+- Bulk deletion (>5 emails) or bulk operations (>10 emails)
+- Creating/modifying system labels
+
+## Auto-Execute
+- Reading, listing, and searching emails
+- Moving emails to trash
+- Adding/removing labels
+- Creating custom labels
+
+## Tool Operations
+
+### Email Retrieval
+**Tools:** listEmails, getEmail, searchEmails
+- Use appropriate filters to limit results
+- Format lists: sender, subject, date, labels, unread status
+- Show newest first unless specified
+- Display full content when requested
+
+### Email Management
+**Tools:** trashEmail, deleteEmail, batchModifyEmails
+- Use trashEmail for safer removal (recoverable)
+- Use deleteEmail only for permanent deletion
+- Batch operations for efficiency with multiple emails
+
+### Label Management
+**Tools:** listLabels, createLabel, updateLabel, deleteLabel, addLabelsToEmail, removeLabelsFromEmail
+- Create descriptive label names
+- Use colors and visibility settings appropriately
+- Apply labels systematically
+
+### Email Composition
+**Tools:** sendEmail
+- Draft emails with clear subject lines
+- Include all necessary recipients
+- Format content appropriately
+
+Always ask for approval before sending emails or performing destructive operations.
+`;
+//# sourceMappingURL=v2.js.map

package/dist/core/agent/prompts/gmail/v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.js","sourceRoot":"","sources":["../../../../../src/core/agent/prompts/gmail/v2.ts"],"names":[],"mappings":";;;AAAa,QAAA,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsD9B,CAAC"}

package/dist/core/agent/tools/base-tool.d.ts

@@ -0,0 +1,161 @@
+import { Effect } from "effect";
+import { z } from "zod";
+import { type Tool, type ToolExecutionContext, type ToolExecutionResult } from "./tool-registry";
+/**
+ * Lightweight, reusable tool builder with optional runtime validation.
+ * Keeps JSON Schema as-is for LLMs and applies a simple validator at runtime.
+ */
+export interface ToolValidatorResult<Args extends Record<string, unknown>> {
+    readonly valid: boolean;
+    readonly value?: Args;
+    readonly errors?: readonly string[];
+}
+export type ToolValidator<Args extends Record<string, unknown>> = (args: Record<string, unknown>) => ToolValidatorResult<Args>;
+export interface BaseToolConfig<R, Args extends Record<string, unknown>> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: z.ZodTypeAny;
+    /** If true, hide this tool from UI listings while keeping it callable. */
+    readonly hidden?: boolean;
+    /**
+     * Optional function to validate the tool arguments before execution.
+     *
+     * This validator runs after the LLM provides arguments but before the handler
+     * is called. It provides runtime type checking and custom validation logic
+     * beyond what JSON Schema can express. The validator should return a result
+     * indicating whether the arguments are valid and provide any error messages
+     * for invalid inputs.
+     *
+     * @example
+     * ```typescript
+     * validate: (args) => {
+     *   if (args.email && !args.email.includes('@')) {
+     *     return { valid: false, errors: ['Invalid email format'] };
+     *   }
+     *   return { valid: true, value: args };
+     * }
+     * ```
+     */
+    readonly validate?: ToolValidator<Args>;
+    /**
+     * Optional approval requirement for destructive tools.
+     * If provided, the tool will ALWAYS show the approval message and require user confirmation.
+     * The LLM cannot bypass this by setting any field - it must ask the user for confirmation.
+     */
+    readonly approval?: {
+        /**
+         * Create a human-readable message explaining what will happen.
+         * Used to guide the agent to ask the user for confirmation.
+         * Can be async to fetch additional context (like email details).
+         */
+        readonly message: (args: Args, context: ToolExecutionContext) => Effect.Effect<string, Error, R>;
+        /**
+         * Custom error message when approval is required. Defaults to generic message.
+         */
+        readonly errorMessage?: string;
+        /**
+         * Optional execution callback that defines which tool to call on user approval
+         * and how to build its arguments from the validated input.
+         */
+        readonly execute?: {
+            readonly toolName: string;
+            readonly buildArgs: (args: Args) => Record<string, unknown>;
+        };
+    };
+    /**
+     * The main function that handles the tool execution logic.
+     *
+     * This is the core implementation of the tool that performs the actual work.
+     * It receives validated arguments and execution context, and returns an Effect
+     * that represents the asynchronous operation. The handler should handle all
+     * business logic, external API calls, file operations, or other side effects
+     * required by the tool.
+     *
+     * The function must return a ToolExecutionResult that indicates success or failure,
+     * along with any relevant data or error messages. All side effects should be
+     * wrapped in Effect to ensure proper error handling and resource management.
+     *
+     * @param args - The validated arguments passed to the tool
+     * @param context - The execution context containing environment, logger, and other services
+     * @returns An Effect that resolves to a ToolExecutionResult
+     *
+     * @example
+     * ```typescript
+     * handler: (args, context) => Effect.gen(function* () {
+     *   const logger = yield* context.logger;
+     *   yield* logger.info(`Processing request: ${args.id}`);
+     *
+     *   const result = yield* processRequest(args);
+     *   return { success: true, result };
+     * })
+     * ```
+     */
+    readonly handler: (args: Args, context: ToolExecutionContext) => Effect.Effect<ToolExecutionResult, Error, R>;
+    /**
+     * Optional function to create a human-readable summary of the tool execution result.
+     *
+     * This function is called after the tool execution completes successfully and is used
+     * to generate a concise, user-friendly summary of what the tool accomplished. The
+     * summary is typically displayed to the user or logged for audit purposes. If not
+     * provided, a default summary will be generated based on the tool name and success status.
+     *
+     * The function receives the complete ToolExecutionResult and should return a string
+     * that clearly describes the outcome. Return undefined to use the default summary
+     * generation logic.
+     *
+     * @param result - The complete execution result from the tool handler
+     * @returns A human-readable summary string, or undefined to use default summary
+     *
+     * @example
+     * ```typescript
+     * createSummary: (result) => {
+     *   if (result.success && result.result) {
+     *     return `Successfully processed ${result.result.count} items`;
+     *   }
+     *   return `Tool execution ${result.success ? 'succeeded' : 'failed'}`;
+     * }
+     * ```
+     */
+    readonly createSummary?: (result: ToolExecutionResult) => string | undefined;
+}
+/**
+ * Define a new tool with validation and approval capabilities
+ *
+ * Creates a tool from the provided configuration, including optional validation
+ * and approval requirements. The tool can be configured to require user approval
+ * for destructive operations and includes comprehensive argument validation.
+ *
+ * @param config - The tool configuration including name, description, parameters, validation, and approval settings
+ * @returns A Tool object that can be registered and executed
+ *
+ * @example
+ * ```typescript
+ * const emailTool = defineTool({
+ *   name: "send_email",
+ *   description: "Send an email to a recipient",
+ *   parameters: {
+ *     to: { type: "string", description: "Recipient email address" },
+ *     subject: { type: "string", description: "Email subject" }
+ *   },
+ *   handler: async (args, context) => {
+ *     // Tool implementation
+ *     return { success: true, result: "Email sent" };
+ *   }
+ * });
+ * ```
+ */
+export declare function defineTool<R, Args extends Record<string, unknown>>(config: BaseToolConfig<R, Args>): Tool<R>;
+/**
+ * Build a minimal runtime validator from a JSON Schema subset.
+ * Supports: type = string|number|boolean|array(object: items.type), required[], additionalProperties.
+ */
+export declare function makeJsonSchemaValidator<Args extends Record<string, unknown>>(schema: Record<string, unknown>): ToolValidator<Args>;
+/**
+ * Utility to extend a JSON schema object with a standard approval boolean field.
+ * This does not mutate the original schema object.
+ */
+export declare function withApprovalBoolean(schema: z.ZodTypeAny, options?: {
+    fieldName?: string;
+    description?: string;
+}): z.ZodTypeAny;
+//# sourceMappingURL=base-tool.d.ts.map

package/dist/core/agent/tools/base-tool.d.ts.map

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

package/dist/core/agent/tools/base-tool.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
+exports.makeJsonSchemaValidator = makeJsonSchemaValidator;
+exports.withApprovalBoolean = withApprovalBoolean;
+const effect_1 = require("effect");
+const zod_1 = require("zod");
+/**
+ * Define a new tool with validation and approval capabilities
+ *
+ * Creates a tool from the provided configuration, including optional validation
+ * and approval requirements. The tool can be configured to require user approval
+ * for destructive operations and includes comprehensive argument validation.
+ *
+ * @param config - The tool configuration including name, description, parameters, validation, and approval settings
+ * @returns A Tool object that can be registered and executed
+ *
+ * @example
+ * ```typescript
+ * const emailTool = defineTool({
+ *   name: "send_email",
+ *   description: "Send an email to a recipient",
+ *   parameters: {
+ *     to: { type: "string", description: "Recipient email address" },
+ *     subject: { type: "string", description: "Email subject" }
+ *   },
+ *   handler: async (args, context) => {
+ *     // Tool implementation
+ *     return { success: true, result: "Email sent" };
+ *   }
+ * });
+ * ```
+ */
+function defineTool(config) {
+    return {
+        name: config.name,
+        description: config.description,
+        parameters: config.parameters,
+        hidden: config.hidden === true,
+        createSummary: config.createSummary,
+        execute(args, context) {
+            if (config.validate) {
+                const result = config.validate(args);
+                if (!result.valid) {
+                    const message = (result.errors || ["Invalid arguments"]).join("; ");
+                    return effect_1.Effect.succeed({ success: false, result: null, error: message });
+                }
+                const validated = result.value;
+                // Enforce approval if configured
+                if (config.approval) {
+                    // Return an approval request payload
+                    return effect_1.Effect.gen(function* () {
+                        const approval = config.approval;
+                        const approvalMessage = yield* approval.message(validated, context);
+                        const execute = approval.execute;
+                        return {
+                            success: false,
+                            result: {
+                                approvalRequired: true,
+                                message: approvalMessage,
+                                ...(execute
+                                    ? {
+                                        instruction: `Please ask the user for confirmation. If they confirm, call this tool again with { "confirm": true } or call: ${execute.toolName} with these exact arguments: ${JSON.stringify(execute.buildArgs(validated))}`,
+                                        executeToolName: execute.toolName,
+                                        executeArgs: execute.buildArgs(validated),
+                                    }
+                                    : {}),
+                            },
+                            error: approval.errorMessage ??
+                                "Approval required: This action requires user confirmation.",
+                        };
+                    });
+                }
+                return config.handler(validated, context);
+            }
+            // No validation configured; pass through
+            return config.handler(args, context);
+        },
+    };
+}
+/**
+ * Build a minimal runtime validator from a JSON Schema subset.
+ * Supports: type = string|number|boolean|array(object: items.type), required[], additionalProperties.
+ */
+function makeJsonSchemaValidator(schema) {
+    return (args) => {
+        const errors = [];
+        const s = schema;
+        if (s.type !== undefined && s.type !== "object") {
+            errors.push("Root schema.type must be 'object'");
+        }
+        const properties = (s.properties || {});
+        const required = new Set((s.required || []));
+        for (const key of required) {
+            if (!(key in args)) {
+                errors.push(`Missing required property: ${key}`);
+            }
+        }
+        for (const [key, value] of Object.entries(args)) {
+            const prop = properties[key];
+            if (!prop) {
+                if (s.additionalProperties === false) {
+                    errors.push(`Unknown property: ${key}`);
+                }
+                continue;
+            }
+            const expected = prop.type;
+            if (!expected)
+                continue;
+            const actual = typeof value;
+            if (expected === "array") {
+                if (!Array.isArray(value)) {
+                    errors.push(`Property '${key}' expected array, got ${actual}`);
+                }
+                else {
+                    const itemType = prop.items?.type;
+                    if (itemType) {
+                        for (let i = 0; i < value.length; i++) {
+                            const t = typeof value[i];
+                            if (t !== itemType) {
+                                errors.push(`Property '${key}[${i}]' expected ${itemType}, got ${t}`);
+                            }
+                        }
+                    }
+                }
+            }
+            else if (actual !== expected) {
+                errors.push(`Property '${key}' expected ${expected}, got ${actual}`);
+            }
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        return { valid: true, value: args };
+    };
+}
+/**
+ * Utility to extend a JSON schema object with a standard approval boolean field.
+ * This does not mutate the original schema object.
+ */
+function withApprovalBoolean(schema, options) {
+    const fieldName = options?.fieldName ?? "confirm";
+    const description = options?.description ?? "Set to true to confirm this action.";
+    // If provided a Zod object, extend it in-place with a boolean confirm field
+    if (schema instanceof zod_1.z.ZodObject) {
+        return schema.extend({
+            [fieldName]: zod_1.z.boolean().describe(description),
+        });
+    }
+    // If it's some other Zod type, intersect with an object carrying confirm
+    return zod_1.z.object({ [fieldName]: zod_1.z.boolean().describe(description) }).and(schema);
+}
+//# sourceMappingURL=base-tool.js.map

package/dist/core/agent/tools/base-tool.js.map

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

package/dist/core/agent/tools/fs-tools.d.ts

@@ -0,0 +1,21 @@
+import { FileSystem } from "@effect/platform";
+import { Effect } from "effect";
+import { type FileSystemContextService } from "../../../services/shell";
+import { type Tool } from "./tool-registry";
+export declare function createFindPathTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createPwdTool(): Tool<FileSystemContextService>;
+export declare function createLsTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createCdTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createReadFileTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createWriteFileTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createExecuteWriteFileTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createGrepTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createFindTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createMkdirTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createExecuteMkdirTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createStatTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createRmTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createExecuteRmTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function createFindDirTool(): Tool<FileSystem.FileSystem | FileSystemContextService>;
+export declare function registerFileTools(): Effect.Effect<void, Error, FileSystem.FileSystem>;
+//# sourceMappingURL=fs-tools.d.ts.map

package/dist/core/agent/tools/fs-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-tools.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/tools/fs-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,KAAK,IAAI,EAA6B,MAAM,iBAAiB,CAAC;AAoCvE,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAiK3F;AAGD,wBAAgB,aAAa,IAAI,IAAI,CAAC,wBAAwB,CAAC,CAmB9D;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAqIrF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA4DrF;AAGD,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAmI3F;AAKD,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAiD5F;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAChD,UAAU,CAAC,UAAU,GAAG,wBAAwB,CACjD,CAsDA;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAqMvF;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkOvF;AAGD,wBAAgB,eAAe,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0DxF;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0D/F;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkEvF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA8CrF;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA2E5F;AAGD,wBAAgB,iBAAiB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAyD1F;AAGD,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAGrF"}