machinaos 0.0.10 → 0.0.13

package/server/skills/social_agent/whatsapp-send-skill/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: whatsapp-send-skill
+description: Send WhatsApp messages to contacts or groups. Supports text, images, videos, audio, documents, stickers, locations, and contacts.
+allowed-tools: whatsapp_send
+metadata:
+  author: machina
+  version: "1.0"
+  category: messaging
+  icon: "📤"
+  color: "#25D366"
+---
+
+# WhatsApp Send Tool
+
+Send messages to WhatsApp contacts or groups.
+
+## How It Works
+
+This skill provides instructions for the **WhatsApp Send** tool node. Connect the **WhatsApp Send** node to Zeenie's `input-tools` handle to enable message sending.
+
+## whatsapp_send Tool
+
+Send messages to individual contacts or groups.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| recipient_type | string | Yes | `"phone"` for individual or `"group"` for group chat |
+| phone | string | If phone | Phone number without + prefix (e.g., `1234567890`) |
+| group_id | string | If group | Group JID (e.g., `123456789@g.us`) |
+| message_type | string | Yes | Message type (see below) |
+| message | string | If text | Text message content |
+| media_url | string | If media | URL for image/video/audio/document/sticker |
+| caption | string | No | Caption for media messages |
+| latitude | float | If location | Latitude coordinate |
+| longitude | float | If location | Longitude coordinate |
+| location_name | string | No | Display name for location |
+| address | string | No | Address text for location |
+| contact_name | string | If contact | Contact display name |
+| vcard | string | If contact | vCard 3.0 format string |
+
+### Message Types
+
+| Type | Required Fields | Description |
+|------|-----------------|-------------|
+| `text` | message | Plain text message |
+| `image` | media_url | Image file (JPG, PNG, GIF) |
+| `video` | media_url | Video file (MP4) |
+| `audio` | media_url | Audio file (MP3, OGG, WAV) |
+| `document` | media_url | Any file type |
+| `sticker` | media_url | Sticker image (WebP) |
+| `location` | latitude, longitude | GPS coordinates |
+| `contact` | contact_name, vcard | Contact card |
+
+### Examples
+
+**Send text message to contact:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "text",
+  "message": "Hello! How are you?"
+}
+```
+
+**Send image with caption:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "image",
+  "media_url": "https://example.com/photo.jpg",
+  "caption": "Check out this photo!"
+}
+```
+
+**Send to group:**
+```json
+{
+  "recipient_type": "group",
+  "group_id": "123456789012345678@g.us",
+  "message_type": "text",
+  "message": "Hello everyone!"
+}
+```
+
+**Send video:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "video",
+  "media_url": "https://example.com/video.mp4",
+  "caption": "Check this video"
+}
+```
+
+**Send document:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "document",
+  "media_url": "https://example.com/report.pdf",
+  "caption": "Here's the report"
+}
+```
+
+**Send location:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "location",
+  "latitude": 37.7749,
+  "longitude": -122.4194,
+  "location_name": "San Francisco",
+  "address": "San Francisco, CA, USA"
+}
+```
+
+**Send contact card:**
+```json
+{
+  "recipient_type": "phone",
+  "phone": "1234567890",
+  "message_type": "contact",
+  "contact_name": "John Doe",
+  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD"
+}
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "recipient": "1234567890",
+  "recipient_type": "phone",
+  "message_type": "text",
+  "details": {
+    "status": "sent",
+    "preview": "Hello! How are you?",
+    "timestamp": "2025-01-30T12:00:00"
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "Phone number is required for recipient_type='phone'"
+}
+```
+
+## Guidelines
+
+1. **Phone numbers**: Always use without + prefix, just digits (e.g., `919876543210`)
+2. **Group IDs**: Use JID format ending in `@g.us` (e.g., `123456789@g.us`)
+3. **Media URLs**: Must be publicly accessible URLs (https://)
+4. **vCard format**: Use vCard 3.0 specification for contact cards
+5. **Message length**: Text messages can be up to 4096 characters
+6. **Media size**: Check WhatsApp limits for media file sizes
+
+## Common Use Cases
+
+- Send automated notifications to contacts
+- Forward messages to groups
+- Share media files
+- Send location information
+- Share contact information
+
+## Setup Requirements
+
+1. Connect the **WhatsApp Send** node to Zeenie's `input-tools` handle
+2. Ensure WhatsApp is connected (green status indicator in Credentials)
+3. The recipient must have WhatsApp installed

package/server/skills/task_agent/cron-scheduler-skill/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: cron-scheduler-skill
+description: Schedule recurring tasks using cron expressions. Run workflows on schedules (daily, weekly, hourly, etc.).
+allowed-tools: cron_scheduler
+metadata:
+  author: machina
+  version: "1.0"
+  category: automation
+  icon: "📅"
+  color: "#8B5CF6"
+---
+
+# Cron Scheduler Tool
+
+Schedule recurring tasks using cron expressions.
+
+## How It Works
+
+This skill provides instructions for the **Cron Scheduler** tool node. Connect the **Cron Scheduler** node to Zeenie's `input-tools` handle or use as a workflow trigger.
+
+## cron_scheduler Tool
+
+Create recurring schedules using cron expressions.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| expression | string | Yes | Cron expression (5 fields) |
+| timezone | string | No | Timezone (default: UTC) |
+
+### Cron Expression Format
+
+```
+* * * * *
+│ │ │ │ │
+│ │ │ │ └── Day of week (0-7, Sun=0 or 7)
+│ │ │ └──── Month (1-12)
+│ │ └────── Day of month (1-31)
+│ └──────── Hour (0-23)
+└────────── Minute (0-59)
+```
+
+### Special Characters
+
+| Character | Meaning | Example |
+|-----------|---------|---------|
+| `*` | Any value | `* * * * *` (every minute) |
+| `,` | List of values | `1,15 * * * *` (minute 1 and 15) |
+| `-` | Range | `1-5 * * * *` (minutes 1-5) |
+| `/` | Step values | `*/15 * * * *` (every 15 minutes) |
+
+### Common Patterns
+
+| Pattern | Description | Cron Expression |
+|---------|-------------|-----------------|
+| Every minute | Runs each minute | `* * * * *` |
+| Every 5 minutes | Runs at :00, :05, :10... | `*/5 * * * *` |
+| Every 15 minutes | Runs at :00, :15, :30, :45 | `*/15 * * * *` |
+| Every hour | Runs at minute 0 | `0 * * * *` |
+| Every day at 9 AM | Morning job | `0 9 * * *` |
+| Every day at midnight | Nightly job | `0 0 * * *` |
+| Weekdays at 9 AM | Mon-Fri morning | `0 9 * * 1-5` |
+| Every Monday | Weekly on Monday | `0 0 * * 1` |
+| First of month | Monthly job | `0 0 1 * *` |
+| Every Sunday at 6 PM | Weekly Sunday evening | `0 18 * * 0` |
+| Multiple times daily | 8am, noon, 6pm | `0 8,12,18 * * *` |
+
+### Examples
+
+**Every day at 9 AM:**
+```json
+{
+  "expression": "0 9 * * *",
+  "timezone": "America/New_York"
+}
+```
+
+**Every 30 minutes:**
+```json
+{
+  "expression": "*/30 * * * *"
+}
+```
+
+**Weekdays at 6 PM:**
+```json
+{
+  "expression": "0 18 * * 1-5",
+  "timezone": "Europe/London"
+}
+```
+
+**Every Monday at 10 AM:**
+```json
+{
+  "expression": "0 10 * * 1",
+  "timezone": "Asia/Tokyo"
+}
+```
+
+**First day of each month:**
+```json
+{
+  "expression": "0 0 1 * *"
+}
+```
+
+### Response Format
+
+**Schedule created:**
+```json
+{
+  "success": true,
+  "message": "Cron schedule created",
+  "expression": "0 9 * * *",
+  "timezone": "America/New_York",
+  "next_run": "2025-01-31T09:00:00-05:00",
+  "description": "At 09:00 AM, every day"
+}
+```
+
+**Schedule triggered:**
+```json
+{
+  "success": true,
+  "triggered": true,
+  "message": "Cron schedule triggered",
+  "expression": "0 9 * * *",
+  "triggered_at": "2025-01-30T09:00:00Z"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "Invalid cron expression: too few fields"
+}
+```
+
+## Timezone Reference
+
+| Timezone | Description |
+|----------|-------------|
+| `UTC` | Universal Time (default) |
+| `America/New_York` | Eastern US |
+| `America/Los_Angeles` | Pacific US |
+| `Europe/London` | UK |
+| `Europe/Paris` | Central Europe |
+| `Asia/Tokyo` | Japan |
+| `Asia/Shanghai` | China |
+| `Australia/Sydney` | Australia Eastern |
+
+## Use Cases
+
+| Use Case | Expression | Description |
+|----------|------------|-------------|
+| Daily report | `0 9 * * *` | Generate daily reports |
+| Hourly sync | `0 * * * *` | Sync data hourly |
+| Weekly backup | `0 2 * * 0` | Sunday at 2 AM |
+| Business hours check | `*/30 9-17 * * 1-5` | Every 30 min, 9-5 Mon-Fri |
+| Monthly cleanup | `0 0 1 * *` | First of month |
+
+## Common Workflows
+
+### Daily notification
+
+1. Set cron for desired time (e.g., `0 9 * * *`)
+2. Cron triggers → workflow runs
+3. Send notification to user
+
+### Scheduled data sync
+
+1. Set cron for sync interval (e.g., `0 * * * *`)
+2. Cron triggers → fetch data
+3. Process and store data
+
+### Weekly report
+
+1. Set cron for weekly (e.g., `0 10 * * 1`)
+2. Cron triggers → generate report
+3. Send report via email/WhatsApp
+
+## Workflow-Based Scheduling
+
+In this system, scheduling works through:
+
+1. **Trigger Node**: Use Cron Scheduler as workflow start
+2. **Deployment**: Deploy workflow to activate schedule
+3. **Cancellation**: Undeploy workflow to stop schedule
+
+Each trigger creates independent workflow runs.
+
+## Best Practices
+
+1. **Use UTC for global**: Avoid timezone confusion
+2. **Consider load**: Don't schedule many jobs at :00
+3. **Stagger jobs**: Use :05, :10 instead of all at :00
+4. **Test expressions**: Verify with online cron tools
+5. **Document schedules**: Keep track of what runs when
+
+## Limitations
+
+- Requires workflow deployment to activate
+- Cannot schedule past events
+- Minimum granularity is 1 minute
+- Complex conditions need multiple schedules
+
+## Setup Requirements
+
+1. Connect the **Cron Scheduler** node to Zeenie's `input-tools` handle
+2. Or use as workflow trigger (first node)
+3. Deploy workflow to activate the schedule
+4. Undeploy to cancel the schedule

package/server/skills/task_agent/task-manager-skill/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: task-manager-skill
+description: Manage delegated tasks. List active tasks, check task status, get results from completed delegations, and mark tasks as done.
+allowed-tools: task_manager
+metadata:
+  author: machina
+  version: "1.0"
+  category: automation
+  icon: "📋"
+  color: "#F59E0B"
+---
+
+# Task Manager Tool
+
+Manage and track delegated agent tasks.
+
+## How It Works
+
+This skill provides instructions for the **Task Manager** tool node. Connect the **Task Manager** node to Zeenie's `input-tools` handle to enable task management operations.
+
+## task_manager Tool
+
+List, check, and manage delegated tasks.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| operation | string | Yes | `"list_tasks"`, `"get_task"`, or `"mark_done"` |
+| task_id | string | For get_task, mark_done | Specific task ID to query |
+| status_filter | string | No | Filter by status: `"running"`, `"completed"`, `"error"` |
+
+### Operations
+
+| Operation | Description | Required Fields |
+|-----------|-------------|-----------------|
+| `list_tasks` | List all tracked tasks | status_filter (optional) |
+| `get_task` | Get details for specific task | task_id |
+| `mark_done` | Remove task from tracking | task_id |
+
+### Task States
+
+| Status | Description |
+|--------|-------------|
+| `running` | Task is currently executing |
+| `completed` | Task finished successfully |
+| `error` | Task failed with error |
+| `cancelled` | Task was cancelled |
+
+### Examples
+
+**List all tasks:**
+```json
+{
+  "operation": "list_tasks"
+}
+```
+
+**List only running tasks:**
+```json
+{
+  "operation": "list_tasks",
+  "status_filter": "running"
+}
+```
+
+**List completed tasks:**
+```json
+{
+  "operation": "list_tasks",
+  "status_filter": "completed"
+}
+```
+
+**Get specific task details:**
+```json
+{
+  "operation": "get_task",
+  "task_id": "delegated_agent_abc12345"
+}
+```
+
+**Mark task as done:**
+```json
+{
+  "operation": "mark_done",
+  "task_id": "delegated_agent_abc12345"
+}
+```
+
+### Response Formats
+
+**list_tasks response:**
+```json
+{
+  "success": true,
+  "operation": "list_tasks",
+  "tasks": [
+    {
+      "task_id": "delegated_coding_agent_abc12345",
+      "status": "completed",
+      "agent_name": "Coding Agent",
+      "result_summary": "Generated Python function for data processing...",
+      "active": false
+    },
+    {
+      "task_id": "delegated_web_agent_def67890",
+      "status": "running",
+      "active": true
+    }
+  ],
+  "count": 2,
+  "running": 1,
+  "completed": 1,
+  "errors": 0
+}
+```
+
+**get_task response (completed):**
+```json
+{
+  "success": true,
+  "operation": "get_task",
+  "task_id": "delegated_coding_agent_abc12345",
+  "status": "completed",
+  "agent_name": "Coding Agent",
+  "result": "Here is the Python function you requested:\n\ndef process_data(items):\n    return [x * 2 for x in items]"
+}
+```
+
+**get_task response (running):**
+```json
+{
+  "success": true,
+  "operation": "get_task",
+  "task_id": "delegated_web_agent_def67890",
+  "status": "running",
+  "agent_name": "Web Agent"
+}
+```
+
+**get_task response (error):**
+```json
+{
+  "success": true,
+  "operation": "get_task",
+  "task_id": "delegated_agent_xyz99999",
+  "status": "error",
+  "agent_name": "Social Agent",
+  "error": "Failed to connect to WhatsApp service"
+}
+```
+
+**mark_done response:**
+```json
+{
+  "success": true,
+  "operation": "mark_done",
+  "task_id": "delegated_coding_agent_abc12345",
+  "removed": true,
+  "message": "Task delegated_coding_agent_abc12345 marked as done and removed from tracking"
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "task_id is required for get_task operation"
+}
+```
+
+```json
+{
+  "success": false,
+  "error": "Task delegated_agent_notfound not found",
+  "task_id": "delegated_agent_notfound"
+}
+```
+
+## Use Cases
+
+| Use Case | Operation | Description |
+|----------|-----------|-------------|
+| Monitor progress | list_tasks | See all active delegations |
+| Check result | get_task | Get completed task output |
+| Verify completion | get_task | Confirm task finished |
+| Clean up | mark_done | Remove processed tasks |
+| Error handling | list_tasks + filter | Find failed tasks |
+
+## Common Workflows
+
+### Check on delegated work
+
+1. Delegate task to sub-agent
+2. Wait or continue with other work
+3. Use `list_tasks` to see status
+4. Use `get_task` to retrieve result
+
+### Process all completed tasks
+
+1. Use `list_tasks` with `status_filter: "completed"`
+2. For each task, use `get_task` to get full result
+3. Process the results
+4. Use `mark_done` to clean up
+
+### Handle errors
+
+1. Use `list_tasks` with `status_filter: "error"`
+2. Review failed tasks
+3. Decide to retry or mark_done
+4. Optionally re-delegate failed work
+
+## Integration with Agent Delegation
+
+When a parent agent delegates work:
+
+1. `delegate_to_<agent>` tool returns `task_id`
+2. Child agent runs in background
+3. Parent can check status with `task_manager`
+4. Results persist until `mark_done`
+
+### Task ID Format
+
+Task IDs follow the pattern:
+```
+delegated_<node_id>_<random_hex>
+```
+
+Example: `delegated_coding_agent_1_abc12345`
+
+## Best Practices
+
+1. **Track task IDs**: Store returned task_ids for later reference
+2. **Poll appropriately**: Don't check too frequently
+3. **Handle all states**: Account for running, completed, and error
+4. **Clean up**: Use mark_done after processing results
+5. **Check errors**: Review failed tasks before marking done
+
+## Limitations
+
+- Tasks not persistent across server restarts (in-memory)
+- Results may be truncated if very large (4000 char limit in responses)
+- Cannot cancel running tasks (only track status)
+
+## Setup Requirements
+
+1. Connect the **Task Manager** node to Zeenie's `input-tools` handle
+2. Works with any agent that uses delegation
+3. Task IDs are returned when delegating to sub-agents