@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/docs/low-code-editor/tools.md

@@ -0,0 +1,358 @@
+# Tools
+
+Tools are reusable functions that agents can call to perform specific actions like processing payments, sending emails, or updating databases.
+
+## Tool Structure
+
+Every tool must implement the `Tool` interface:
+
+```ts
+interface Tool<Input extends z.ZodSchema, Memory> {
+  name: string; // Unique tool identifier
+  description: string; // What the tool does (used by LLM)
+  input: Input; // Zod schema for input validation
+  isGlobal?: boolean; // Optional: available across all LLM calls
+  execute: ({ input, state, agent }) => Promise<{ result? }>;
+}
+```
+
+## Execute Function Signature
+
+The `execute` function is the core of every tool. It receives validated input from the LLM, current state (including memory), and the agent instance, then modifies state by reference and returns an optional result.
+
+### Parameters
+
+```ts
+execute: ({ input, state, agent }) => Promise<{ result? }>;
+```
+
+- **`input`**: Validated data matching your Zod schema - contains the parameters the LLM extracted from the conversation
+- **`state`**: Current conversation state including memory, sessionId, and other context data
+- **`agent`**: Agent instance providing access to PII gateway, logging, and other platform features
+
+### Return Value
+
+The execute function returns a Promise with an object containing:
+
+- **`result?`** (optional): Result that gets sent back to the LLM as the tool's response
+
+**Important v2.0 Change**: State is now updated by reference directly within the execute function. You no longer return state updates - instead, modify the state object directly.
+
+## State Object Structure
+
+The `state` object contains:
+
+- **`memory`**: Your user-defined memory schema - the main working memory for your agent
+- **`sessionId`**: Unique identifier for the current session
+- **`messages`**: Array of conversation messages (AI, Human, System, etc.)
+- **`history`**: Array of HistoryStep objects tracking the flow execution (node visits, trigger events, tool calls)
+- **Other platform context**: Additional fields managed by the platform
+
+## Basic Tool Example
+
+Here's a simple refund processing tool:
+
+```ts
+import { z } from 'zod';
+import { Tool } from 'mindedjs/src/types/Tools.types';
+import { logger } from 'mindedjs';
+import memorySchema from '../schema';
+
+type Memory = z.infer<typeof memorySchema>;
+
+const schema = z.object({
+  orderId: z.string(),
+  customerName: z.string(),
+});
+
+const refundOrderTool: Tool<typeof schema, Memory> = {
+  name: 'refundOrder',
+  description: 'Process a customer refund for their order',
+  input: schema,
+  execute: async ({ input, state, agent }) => {
+    // Access current memory
+    const currentMemory = state.memory;
+
+    // Use the provided logger [[memory:4133901]]
+    logger.info('Processing refund', {
+      sessionId: state.sessionId,
+      orderId: input.orderId,
+    });
+
+    // Your business logic here
+    const refundAmount = await processRefundInSystem(input.orderId);
+
+    // Update state directly by reference (v2.0 change)
+    state.memory.orderId = input.orderId;
+    state.memory.customerName = input.customerName;
+    state.memory.issue = `Refund processed: $${refundAmount}`;
+
+    // Only return result, no state
+    return {
+      result: `Refund processed successfully for order ${input.orderId}`,
+    };
+  },
+};
+
+export default refundOrderTool;
+```
+
+## Input Schema Configuration
+
+Input schemas use Zod for validation and provide important metadata to help the LLM understand how to better use each input parameter.
+
+### Parameter Descriptions
+
+Add descriptions to parameters using Zod's `.describe()` method. These descriptions help the LLM understand what each parameter represents:
+
+```ts
+const schema = z.object({
+  orderId: z.string().describe('The unique identifier of the customer order to process'),
+  customerName: z.string().describe('Full name of the customer requesting the refund'),
+  refundAmount: z.number().describe('Amount to refund in dollars (optional if full refund)'),
+  reason: z.string().describe('Reason for the refund request'),
+});
+```
+
+### Optional Parameters
+
+Make parameters optional using Zod's `.optional()` method. Optional parameters don't need to be provided by the LLM:
+
+```ts
+const schema = z.object({
+  orderId: z.string().describe('The unique identifier of the customer order'),
+  customerName: z.string().describe('Full name of the customer'),
+  refundAmount: z.number().optional().describe('Specific refund amount, defaults to full order amount'),
+  expedited: z.boolean().optional().describe('Whether to expedite the refund process'),
+});
+```
+
+### Combining Descriptions and Optional Parameters
+
+You can chain Zod methods to create descriptive optional parameters:
+
+```ts
+const updateOrderSchema = z.object({
+  orderId: z.string().describe('The order ID that needs to be updated'),
+  newAddress: z.string().optional().describe('Updated shipping address if customer wants to change it'),
+  specialInstructions: z.string().optional().describe('Any special delivery instructions from the customer'),
+  urgentDelivery: z.boolean().optional().describe('Whether customer needs urgent delivery (additional charges may apply)'),
+});
+```
+
+## Tool Registration
+
+### Global Tools
+
+Mark tools as global if you want them to be available in all LLM calls.
+
+```ts
+const auditLogTool: Tool<typeof auditSchema, Memory> = {
+  name: 'auditLog',
+  description: 'Log user action for compliance',
+  isGlobal: true, // Available in all flows
+  input: z.object({
+    action: z.string(),
+    details: z.string(),
+  }),
+  execute: async ({ input, state, agent }) => {
+    logger.info('Audit log entry', {
+      sessionId: state.sessionId,
+      action: input.action,
+    });
+
+    await auditService.log({
+      userId: state.memory.userId,
+      action: input.action,
+      details: input.details,
+      timestamp: new Date(),
+    });
+
+    // No return value needed for tools that don't produce results
+    return {};
+  },
+};
+```
+
+## State Management
+
+Tools can read and update state including memory by reference:
+
+```ts
+const updateProfileTool: Tool<typeof profileSchema, Memory> = {
+  name: 'updateProfile',
+  description: 'Update customer profile information',
+  input: z.object({
+    field: z.string(),
+    value: z.string(),
+  }),
+  execute: async ({ input, state, agent }) => {
+    // Read current memory from state
+    console.log(`Current customer: ${state.memory.customerName}`);
+
+    // Update external system
+    await profileService.update(state.memory.customerId, {
+      [input.field]: input.value,
+    });
+
+    // Update state directly by reference (v2.0 change)
+    state.memory[`${input.field}Updated`] = true;
+
+    // No state in return value
+    return {};
+  },
+};
+```
+
+## Error Handling
+
+Handle errors gracefully in tools:
+
+````ts
+const paymentTool: Tool<typeof paymentSchema, Memory> = {
+  name: 'processPayment',
+  description: 'Process customer payment',
+  input: z.object({
+    amount: z.number(),
+    cardToken: z.string(),
+  }),
+  execute: async ({ input, state, agent }) => {
+    try {
+      const result = await paymentService.charge({
+        amount: input.amount,
+        cardToken: input.cardToken,
+        customerId: state.memory.customerId,
+      });
+
+      // Update state directly by reference
+      state.memory.lastPaymentId = result.transactionId;
+
+      return {
+        result: `Payment successful: ${result.transactionId}`,
+      };
+    } catch (err) {
+      logger.error({
+        message: 'Payment failed',
+        sessionId: state.sessionId,
+        err,
+      });
+
+      // Update state directly by reference
+      state.memory.paymentError = err.message;
+
+      return {
+        result: 'Payment failed. Please try again or contact support.',
+      };
+    }
+  },
+};
+
+## Flow Control with goto
+
+Tools can control the flow by setting the `goto` property directly on the state object. This allows tools to programmatically jump to a specific node by setting `state.goto` to the target node ID. This is useful for dynamic flow control based on runtime conditions.
+
+### Basic goto Usage
+
+```ts
+const moveToAnotherRepresentativeTool: Tool<typeof schema, Memory> = {
+  name: 'moveToAnotherRepresentative',
+  description: 'Transfer the conversation to another representative or department',
+  input: schema,
+  execute: async ({ input, state }) => {
+    logger.info({
+      message: 'Moving conversation to another representative',
+      sessionId: state.sessionId,
+      department: input.department,
+      reason: input.reason,
+      priority: input.priority,
+    });
+
+    // Update state directly by reference (v2.0 change)
+    state.goto = 'share-new-representative';
+    state.memory.orderId = 'share-new-representative';
+
+    return {};
+  },
+};
+```
+
+### Dynamic Routing Example
+
+```typescript
+const routingTool: Tool<typeof routingSchema, Memory> = {
+  name: 'routingTool',
+  description: 'Route conversation based on urgency',
+  input: routingSchema,
+  execute: async ({ input, state }) => {
+    // Perform logic to determine routing
+    if (input.condition === 'urgent') {
+      // Jump to urgent handler node by updating state directly
+      state.goto = 'urgent-handler-node';
+
+      return {
+        result: 'Routing to urgent handler',
+      };
+    }
+
+    // Normal flow continues
+    return { result: 'Continue normal flow' };
+  },
+};
+```
+
+> **Important:** The jump occurs only when the current invocation completes and the next one begins. The agent will finish executing the current node/tool before jumping to the specified node.
+
+## Best Practices
+
+1. **Clear Descriptions**: Write descriptions that help the LLM understand when to use the tool
+2. **Input Validation**: Use Zod schemas to validate all inputs
+3. **State Updates**: Update state directly by reference - modify only the parts that need to change
+4. **Error Handling**: Always handle errors gracefully and provide meaningful messages
+5. **Async Operations**: Use async/await for external API calls and database operations
+6. **Logging**: Use the provided logger for consistent, structured logging with session context
+
+## Tool Nodes
+
+Tool nodes force execution of specific tools at defined points in your flow, bypassing LLM decision-making.
+
+### Configuration
+
+```yaml
+nodes:
+  - name: 'Force Refund Processing'
+    type: 'tool'
+    toolName: 'refundOrder'
+````
+
+### Tool Node vs Automatic Tool Calls
+
+| Feature       | Tool Nodes                      | Automatic Tool Calls                |
+| ------------- | ------------------------------- | ----------------------------------- |
+| **Execution** | Guaranteed when node is reached | Only when LLM decides to call       |
+| **Control**   | Explicit flow control           | LLM-driven decision                 |
+| **Use Case**  | Required business logic steps   | Flexible, context-dependent actions |
+
+### Example
+
+```yaml
+nodes:
+  - name: 'Customer Support Start'
+    type: 'prompt'
+    prompt: 'How can I help you today?'
+  - name: 'Log Interaction'
+    type: 'tool'
+    toolName: 'auditLog'
+
+edges:
+  - source: 'Customer Support Start'
+    target: 'Log Interaction'
+    type: 'always'
+```
+
+### Best Practices
+
+1. **Strategic Placement**: Use for critical business logic that must always execute
+2. **Clear Context**: Ensure conversation provides context for parameter extraction
+3. **Error Handling**: Handle errors gracefully since they bypass LLM error recovery
+
+Tool parameters are automatically extracted from conversation context and memory state using an internal LLM agent.

package/docs/low-code-editor/triggers.md

@@ -0,0 +1,182 @@
+# Triggers
+
+Triggers are the entry points into your agent's flows. They serve as the initial contact point between external systems and your agent, handling incoming events and initializing conversations with appropriate context and memory.
+
+## Trigger Types
+
+MindedJS supports three types of triggers:
+
+### 1. Manual Triggers
+
+- **Invocation**: Triggered directly by calling the `agent.invoke()` method in your code
+- **Use Case**: Perfect for testing or programmatic agent invocation
+- **Setup**: No platform configuration required - simply call the method with your parameters
+
+```typescript
+// Manual trigger example
+const result = await agent.invoke({
+  triggerName: 'manual-trigger',
+  triggerBody: { message: 'Hello agent' },
+  sessionId: 'user-session-123',
+});
+```
+
+### 2. App Triggers
+
+- **Invocation**: Triggered by specific applications and external integrations (e.g., Slack, Zendesk)
+- **Setup**: Configured through the Minded platform interface
+- **Identification**: Each app trigger is identified by a unique `appTriggerId`
+- **Data Handling**: Supports automatic message conversion for certain apps (e.g., Slack messages)
+
+### 3. Webhook Triggers
+
+- **Invocation**: Triggered by HTTP requests to specific endpoints in the Minded platform
+- **Setup**: Configured through the Minded platform interface
+- **Agent Specific**: Each webhook trigger belongs to a specific agent and cannot be shared between agents
+- **Use Case**: Ideal for receiving data from external systems, APIs, or third-party services that can send HTTP requests
+
+> **Note**: Both app triggers and webhook triggers are configured and managed through the Minded platform. All triggers are agent-specific and cannot be shared between different agents.
+
+### Trigger Invocation History
+
+When a trigger is invoked, it creates a comprehensive record of the event that is:
+
+1. Added to the flow history for tracking and debugging
+2. Preserved throughout the flow's execution as a history step
+
+This history allows tools and handlers to:
+
+- Access the original trigger context
+- Make decisions based on the triggering event
+- Maintain conversation continuity
+- Debug flow execution
+- Track the agent's execution path through different nodes
+
+Each history step contains the following information:
+
+- `step`: Sequential step number in the agent's execution flow
+- `type`: Type of the step (TRIGGER_NODE, APP_TRIGGER_NODE, TOOL_NODE, etc.)
+- `nodeId`: ID of the node that was executed
+- `nodeDisplayName`: Human-readable name of the node
+- `raw`: Raw data associated with the step (e.g., trigger input, tool output)
+- `messageIds`: IDs of messages associated with this step
+
+Example:
+
+```typescript
+const tool: Tool = {
+  name: 'myTool',
+  execute: async ({ input, state }) => {
+    // Access trigger information from history
+    const triggerStep = state.history.find((step) => step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE');
+
+    if (triggerStep) {
+      console.log(`Processing request from node: ${triggerStep.nodeDisplayName}`);
+
+      // Handle different trigger types based on history
+      if (triggerStep.nodeDisplayName === 'manual-trigger') {
+        // Handle manual trigger
+        console.log('Manual trigger data:', triggerStep.raw);
+      } else if (triggerStep.type === 'APP_TRIGGER_NODE' && triggerStep.appName === 'Slack') {
+        // Handle app trigger from Slack
+        console.log('Slack trigger data:', triggerStep.raw);
+      }
+    }
+
+    return { result: 'Success' };
+  },
+};
+```
+
+### Default Message Behavior
+
+MindedJS provides intelligent message handling for a few app triggers through the `triggerTypeToDefaultMessage` mapping. This system:
+
+- Automatically converts trigger data into appropriate message formats
+- Maintains conversation context without manual intervention
+- Supports different message types for different applications
+- Can be overridden using the `onTriggerEvent` handler
+
+Currently supported default messages:
+
+- **App Triggers (Slack)**: For "New Direct Message (Instant)" triggers, the message text is automatically converted to a human message
+- **Manual Triggers**: No automatic message conversion - you control the flow entirely
+- **Webhook Triggers**: Flexible message handling based on the HTTP payload structure
+
+Example:
+
+```typescript
+// Manual trigger - full control over the flow
+const manualResult = await agent.invoke({
+  triggerName: 'manual-trigger',
+  triggerBody: { customData: 'Hello manually' },
+  sessionId: 'manual-session-123',
+});
+
+// App trigger (Slack) - automatic message conversion
+const slackResult = await agent.invoke({
+  triggerName: 'New Direct Message (Instant)',
+  triggerBody: { text: 'Hello from Slack' },
+  appName: 'Slack',
+});
+
+// Webhook trigger - handled based on HTTP payload
+const webhookResult = await agent.invoke({
+  triggerName: 'webhook-endpoint-name',
+  triggerBody: { payload: 'Hello from webhook' },
+  appName: 'Webhook',
+});
+```
+
+### Validate Trigger Input
+
+```typescript
+// ✅ Good - Input validation
+agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId }) => {
+  if (!triggerBody.customerId || !triggerBody.message) {
+    return { isQualified: false }; // Disqualify invalid triggers
+  }
+  // Process valid trigger
+  return { isQualified: true };
+});
+
+// ❌ Avoid - No validation
+agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody, sessionId }) => {
+  // Process without validation
+  return { isQualified: true };
+});
+```
+
+### Session ID in Trigger Events
+
+The `sessionId` parameter in `TRIGGER_EVENT` is automatically provided by the platform in different environments:
+
+- **Sandbox Playground**: The platform automatically generates and provides a default `sessionId` for each trigger execution. It's important to pass it forward in sandbox environment.
+- **Production Applications**: Users are expected to provide their own `sessionId` if they wish to suppport resuming sessions.
+- **Session Continuity**: When a `sessionId` is provided that matches an existing session, the agent will resume from the previous state instead of starting fresh
+
+## Webhook Headers
+
+When handling webhook triggers, request headers are available through `triggerBody.headers`. This allows you to access important metadata about the incoming request.
+
+### Accessing Headers
+
+```typescript
+agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody }) => {
+  // Access webhook sender's IP address
+  const senderIP = triggerBody.headers?.['x-forwarded-for'];
+
+  // Access other headers
+  const contentType = triggerBody.headers?.['content-type'];
+  const userAgent = triggerBody.headers?.['user-agent'];
+
+  return { isQualified: true };
+});
+```
+
+Common headers available:
+
+- `x-forwarded-for` - Original sender's IP address
+- `content-type` - Request content type
+- `user-agent` - Client user agent string
+- Custom headers sent by the webhook sender