machinaos 0.0.12 → 0.0.13

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

package/server/skills/task_agent/timer-skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: timer-skill
+description: Set one-time delayed timers. Execute actions after a specified duration (seconds, minutes, hours, days).
+allowed-tools: timer
+metadata:
+  author: machina
+  version: "1.0"
+  category: automation
+  icon: "⏱️"
+  color: "#10B981"
+---
+
+# Timer Tool
+
+Set one-time delayed execution timers.
+
+## How It Works
+
+This skill provides instructions for the **Timer** tool node. Connect the **Timer** node to Zeenie's `input-tools` handle to enable timed delays.
+
+## timer Tool
+
+Create a one-time timer that triggers after a specified duration.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| duration | number | Yes | Time value for the delay |
+| unit | string | Yes | Time unit: `"seconds"`, `"minutes"`, `"hours"`, `"days"` |
+
+### Time Units
+
+| Unit | Range | Use Case |
+|------|-------|----------|
+| `seconds` | 1-3600 | Short delays, testing |
+| `minutes` | 1-1440 | Task reminders, short waits |
+| `hours` | 1-168 | Scheduled checks, delayed notifications |
+| `days` | 1-30 | Long-term reminders, follow-ups |
+
+### Examples
+
+**30 second delay:**
+```json
+{
+  "duration": 30,
+  "unit": "seconds"
+}
+```
+
+**5 minute reminder:**
+```json
+{
+  "duration": 5,
+  "unit": "minutes"
+}
+```
+
+**1 hour delay:**
+```json
+{
+  "duration": 1,
+  "unit": "hours"
+}
+```
+
+**2 day follow-up:**
+```json
+{
+  "duration": 2,
+  "unit": "days"
+}
+```
+
+### Response Format
+
+**Timer set:**
+```json
+{
+  "success": true,
+  "message": "Timer set for 5 minutes",
+  "duration": 5,
+  "unit": "minutes",
+  "duration_seconds": 300,
+  "trigger_at": "2025-01-30T12:05:00Z"
+}
+```
+
+**Timer triggered:**
+```json
+{
+  "success": true,
+  "triggered": true,
+  "message": "Timer completed after 5 minutes",
+  "duration": 5,
+  "unit": "minutes"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "Duration must be a positive number"
+}
+```
+
+## Use Cases
+
+| Use Case | Duration | Unit | Description |
+|----------|----------|------|-------------|
+| Quick test | 10-30 | seconds | Testing workflow execution |
+| Reminder | 5-30 | minutes | Short-term reminders |
+| Rate limit | 60 | seconds | Wait between API calls |
+| Daily check | 24 | hours | Daily automation |
+| Follow-up | 2-7 | days | Long-term follow-ups |
+
+## Common Workflows
+
+### Delayed notification
+
+1. Receive user request for reminder
+2. Set timer with requested duration
+3. Timer triggers → send notification
+
+### Rate-limited API calls
+
+1. Make API call
+2. Set 60-second timer
+3. Timer triggers → make next call
+
+### Scheduled workflow
+
+1. Set timer for desired delay
+2. Timer triggers → execute workflow nodes
+
+## Integration with Workflow
+
+When used as a trigger node in a workflow:
+1. Deploy the workflow
+2. Timer countdown begins
+3. After duration, downstream nodes execute
+
+When used as AI tool:
+1. Agent decides to set timer
+2. Timer is scheduled
+3. Agent can proceed with other work
+4. Notification when timer triggers
+
+## Best Practices
+
+1. **Use appropriate units**: Don't use 3600 seconds when 1 hour is clearer
+2. **Consider time zones**: Timers use server time
+3. **Account for drift**: Long timers may have slight variance
+4. **Test short first**: Start with seconds before days
+5. **Chain timers carefully**: Avoid infinite loops
+
+## Limitations
+
+- Timers are not persistent across server restarts
+- Maximum practical delay depends on server uptime
+- Timers are one-time (use cron for recurring)
+
+## Setup Requirements
+
+1. Connect the **Timer** node to Zeenie's `input-tools` handle
+2. For workflow triggers, connect Timer as the first node
+3. Deploy workflow to activate timer