create-ironclaws 1.0.0

package/template/container/agent-runner/src/ipc-mcp-stdio.ts

@@ -0,0 +1,339 @@
+/**
+ * Stdio MCP Server for NanoClaw
+ * Standalone process that agent teams subagents can inherit.
+ * Reads context from environment variables, writes IPC files for the host.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+import { CronExpressionParser } from 'cron-parser';
+
+const IPC_DIR = '/workspace/ipc';
+const MESSAGES_DIR = path.join(IPC_DIR, 'messages');
+const TASKS_DIR = path.join(IPC_DIR, 'tasks');
+
+// Context from environment variables (set by the agent runner)
+const chatJid = process.env.NANOCLAW_CHAT_JID!;
+const groupFolder = process.env.NANOCLAW_GROUP_FOLDER!;
+const isMain = process.env.NANOCLAW_IS_MAIN === '1';
+
+function writeIpcFile(dir: string, data: object): string {
+  fs.mkdirSync(dir, { recursive: true });
+
+  const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`;
+  const filepath = path.join(dir, filename);
+
+  // Atomic write: temp file then rename
+  const tempPath = `${filepath}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tempPath, filepath);
+
+  return filename;
+}
+
+/** Wrap writeIpcFile and return an MCP content array — success or error. */
+function ipcResult(
+  dir: string,
+  data: object,
+  successText: string,
+): { content: Array<{ type: 'text'; text: string }>; isError?: true } {
+  try {
+    writeIpcFile(dir, data);
+    return { content: [{ type: 'text' as const, text: successText }] };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text' as const, text: `IPC write failed: ${msg}` }], isError: true };
+  }
+}
+
+const server = new McpServer({
+  name: 'nanoclaw',
+  version: '1.0.0',
+});
+
+server.tool(
+  'send_message',
+  "Send a message to the user or group immediately while you're still running. Use this for progress updates or to send multiple messages. You can call this multiple times.",
+  {
+    text: z.string().describe('The message text to send'),
+    sender: z.string().optional().describe('Your role/identity name (e.g. "Researcher"). When set, messages appear from a dedicated bot in Telegram.'),
+  },
+  async (args) => {
+    const data: Record<string, string | undefined> = {
+      type: 'message',
+      chatJid,
+      text: args.text,
+      sender: args.sender || undefined,
+      groupFolder,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(MESSAGES_DIR, data, 'Message sent.');
+  },
+);
+
+server.tool(
+  'schedule_task',
+  `Schedule a recurring or one-time task. The task will run as a full agent with access to all tools. Returns the task ID for future reference. To modify an existing task, use update_task instead.
+
+CONTEXT MODE - Choose based on task type:
+\u2022 "group": Task runs in the group's conversation context, with access to chat history. Use for tasks that need context about ongoing discussions, user preferences, or recent interactions.
+\u2022 "isolated": Task runs in a fresh session with no conversation history. Use for independent tasks that don't need prior context. When using isolated mode, include all necessary context in the prompt itself.
+
+If unsure which mode to use, you can ask the user. Examples:
+- "Remind me about our discussion" \u2192 group (needs conversation context)
+- "Check the weather every morning" \u2192 isolated (self-contained task)
+- "Follow up on my request" \u2192 group (needs to know what was requested)
+- "Generate a daily report" \u2192 isolated (just needs instructions in prompt)
+
+MESSAGING BEHAVIOR - The task agent's output is sent to the user or group. It can also use send_message for immediate delivery, or wrap output in <internal> tags to suppress it. Include guidance in the prompt about whether the agent should:
+\u2022 Always send a message (e.g., reminders, daily briefings)
+\u2022 Only send a message when there's something to report (e.g., "notify me if...")
+\u2022 Never send a message (background maintenance tasks)
+
+SCHEDULE VALUE FORMAT (all times are LOCAL timezone):
+\u2022 cron: Standard cron expression (e.g., "*/5 * * * *" for every 5 minutes, "0 9 * * *" for daily at 9am LOCAL time)
+\u2022 interval: Milliseconds between runs (e.g., "300000" for 5 minutes, "3600000" for 1 hour)
+\u2022 once: Local time WITHOUT "Z" suffix (e.g., "2026-02-01T15:30:00"). Do NOT use UTC/Z suffix.`,
+  {
+    prompt: z.string().describe('What the agent should do when the task runs. For isolated mode, include all necessary context here.'),
+    schedule_type: z.enum(['cron', 'interval', 'once']).describe('cron=recurring at specific times, interval=recurring every N ms, once=run once at specific time'),
+    schedule_value: z.string().describe('cron: "*/5 * * * *" | interval: milliseconds like "300000" | once: local timestamp like "2026-02-01T15:30:00" (no Z suffix!)'),
+    context_mode: z.enum(['group', 'isolated']).default('group').describe('group=runs with chat history and memory, isolated=fresh session (include context in prompt)'),
+    target_group_jid: z.string().optional().describe('(Main group only) JID of the group to schedule the task for. Defaults to the current group.'),
+    script: z.string().optional().describe('Optional bash script to run before waking the agent. Script must output JSON on the last line of stdout: { "wakeAgent": boolean, "data"?: any }. If wakeAgent is false, the agent is not called. Test your script with bash -c "..." before scheduling.'),
+  },
+  async (args) => {
+    // Validate schedule_value before writing IPC
+    if (args.schedule_type === 'cron') {
+      try {
+        CronExpressionParser.parse(args.schedule_value);
+      } catch {
+        return {
+          content: [{ type: 'text' as const, text: `Invalid cron: "${args.schedule_value}". Use format like "0 9 * * *" (daily 9am) or "*/5 * * * *" (every 5 min).` }],
+          isError: true,
+        };
+      }
+    } else if (args.schedule_type === 'interval') {
+      const ms = parseInt(args.schedule_value, 10);
+      if (isNaN(ms) || ms <= 0) {
+        return {
+          content: [{ type: 'text' as const, text: `Invalid interval: "${args.schedule_value}". Must be positive milliseconds (e.g., "300000" for 5 min).` }],
+          isError: true,
+        };
+      }
+    } else if (args.schedule_type === 'once') {
+      if (/[Zz]$/.test(args.schedule_value) || /[+-]\d{2}:\d{2}$/.test(args.schedule_value)) {
+        return {
+          content: [{ type: 'text' as const, text: `Timestamp must be local time without timezone suffix. Got "${args.schedule_value}" — use format like "2026-02-01T15:30:00".` }],
+          isError: true,
+        };
+      }
+      const date = new Date(args.schedule_value);
+      if (isNaN(date.getTime())) {
+        return {
+          content: [{ type: 'text' as const, text: `Invalid timestamp: "${args.schedule_value}". Use local time format like "2026-02-01T15:30:00".` }],
+          isError: true,
+        };
+      }
+    }
+
+    // Non-main groups can only schedule for themselves
+    const targetJid = isMain && args.target_group_jid ? args.target_group_jid : chatJid;
+
+    const taskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const data = {
+      type: 'schedule_task',
+      taskId,
+      prompt: args.prompt,
+      script: args.script || undefined,
+      schedule_type: args.schedule_type,
+      schedule_value: args.schedule_value,
+      context_mode: args.context_mode || 'group',
+      targetJid,
+      createdBy: groupFolder,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(TASKS_DIR, data, `Task ${taskId} scheduled: ${args.schedule_type} - ${args.schedule_value}`);
+  },
+);
+
+server.tool(
+  'list_tasks',
+  "List all scheduled tasks. From main: shows all tasks. From other groups: shows only that group's tasks.",
+  {},
+  async () => {
+    const tasksFile = path.join(IPC_DIR, 'current_tasks.json');
+
+    try {
+      if (!fs.existsSync(tasksFile)) {
+        return { content: [{ type: 'text' as const, text: 'No scheduled tasks found.' }] };
+      }
+
+      const allTasks = JSON.parse(fs.readFileSync(tasksFile, 'utf-8'));
+
+      const tasks = isMain
+        ? allTasks
+        : allTasks.filter((t: { groupFolder: string }) => t.groupFolder === groupFolder);
+
+      if (tasks.length === 0) {
+        return { content: [{ type: 'text' as const, text: 'No scheduled tasks found.' }] };
+      }
+
+      const formatted = tasks
+        .map(
+          (t: { id: string; prompt: string; schedule_type: string; schedule_value: string; status: string; next_run: string }) =>
+            `- [${t.id}] ${t.prompt.slice(0, 50)}... (${t.schedule_type}: ${t.schedule_value}) - ${t.status}, next: ${t.next_run || 'N/A'}`,
+        )
+        .join('\n');
+
+      return { content: [{ type: 'text' as const, text: `Scheduled tasks:\n${formatted}` }] };
+    } catch (err) {
+      return {
+        content: [{ type: 'text' as const, text: `Error reading tasks: ${err instanceof Error ? err.message : String(err)}` }],
+      };
+    }
+  },
+);
+
+server.tool(
+  'pause_task',
+  'Pause a scheduled task. It will not run until resumed.',
+  { task_id: z.string().describe('The task ID to pause') },
+  async (args) => {
+    const data = {
+      type: 'pause_task',
+      taskId: args.task_id,
+      groupFolder,
+      isMain,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(TASKS_DIR, data, `Task ${args.task_id} pause requested.`);
+  },
+);
+
+server.tool(
+  'resume_task',
+  'Resume a paused task.',
+  { task_id: z.string().describe('The task ID to resume') },
+  async (args) => {
+    const data = {
+      type: 'resume_task',
+      taskId: args.task_id,
+      groupFolder,
+      isMain,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(TASKS_DIR, data, `Task ${args.task_id} resume requested.`);
+  },
+);
+
+server.tool(
+  'cancel_task',
+  'Cancel and delete a scheduled task.',
+  { task_id: z.string().describe('The task ID to cancel') },
+  async (args) => {
+    const data = {
+      type: 'cancel_task',
+      taskId: args.task_id,
+      groupFolder,
+      isMain,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(TASKS_DIR, data, `Task ${args.task_id} cancellation requested.`);
+  },
+);
+
+server.tool(
+  'update_task',
+  'Update an existing scheduled task. Only provided fields are changed; omitted fields stay the same.',
+  {
+    task_id: z.string().describe('The task ID to update'),
+    prompt: z.string().optional().describe('New prompt for the task'),
+    schedule_type: z.enum(['cron', 'interval', 'once']).optional().describe('New schedule type'),
+    schedule_value: z.string().optional().describe('New schedule value (see schedule_task for format)'),
+    script: z.string().optional().describe('New script for the task. Set to empty string to remove the script.'),
+  },
+  async (args) => {
+    // Validate schedule_value if provided
+    if (args.schedule_type === 'cron' || (!args.schedule_type && args.schedule_value)) {
+      if (args.schedule_value) {
+        try {
+          CronExpressionParser.parse(args.schedule_value);
+        } catch {
+          return {
+            content: [{ type: 'text' as const, text: `Invalid cron: "${args.schedule_value}".` }],
+            isError: true,
+          };
+        }
+      }
+    }
+    if (args.schedule_type === 'interval' && args.schedule_value) {
+      const ms = parseInt(args.schedule_value, 10);
+      if (isNaN(ms) || ms <= 0) {
+        return {
+          content: [{ type: 'text' as const, text: `Invalid interval: "${args.schedule_value}".` }],
+          isError: true,
+        };
+      }
+    }
+
+    const data: Record<string, string | undefined> = {
+      type: 'update_task',
+      taskId: args.task_id,
+      groupFolder,
+      isMain: String(isMain),
+      timestamp: new Date().toISOString(),
+    };
+    if (args.prompt !== undefined) data.prompt = args.prompt;
+    if (args.script !== undefined) data.script = args.script;
+    if (args.schedule_type !== undefined) data.schedule_type = args.schedule_type;
+    if (args.schedule_value !== undefined) data.schedule_value = args.schedule_value;
+
+    return ipcResult(TASKS_DIR, data, `Task ${args.task_id} update requested.`);
+  },
+);
+
+server.tool(
+  'register_group',
+  `Register a new chat/group so the agent can respond to messages there. Main group only.
+
+Use available_groups.json to find the JID for a group. The folder name must be channel-prefixed: "{channel}_{group-name}" (e.g., "whatsapp_family-chat", "telegram_dev-team", "discord_general"). Use lowercase with hyphens for the group name part.`,
+  {
+    jid: z.string().describe('The chat JID (e.g., "120363336345536173@g.us", "tg:-1001234567890", "dc:1234567890123456")'),
+    name: z.string().describe('Display name for the group'),
+    folder: z.string().describe('Channel-prefixed folder name (e.g., "whatsapp_family-chat", "telegram_dev-team")'),
+    trigger: z.string().describe('Trigger word (e.g., "@Andy")'),
+  },
+  async (args) => {
+    if (!isMain) {
+      return {
+        content: [{ type: 'text' as const, text: 'Only the main group can register new groups.' }],
+        isError: true,
+      };
+    }
+
+    const data = {
+      type: 'register_group',
+      jid: args.jid,
+      name: args.name,
+      folder: args.folder,
+      trigger: args.trigger,
+      timestamp: new Date().toISOString(),
+    };
+
+    return ipcResult(TASKS_DIR, data, `Group "${args.name}" registered. It will start receiving messages immediately.`);
+  },
+);
+
+// Start the stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/template/container/agent-runner/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/container/build-argus.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Build the Argus Claude agent container image.
+# This extends nanoclaw-agent:latest with Python, Poetry, gh CLI, and moon.
+#
+# Run from the nanoclaw project root:
+#   ./container/build.sh          # build base image first
+#   ./container/build-argus.sh    # then build the argus image
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+IMAGE_NAME="argus-claude"
+TAG="${1:-latest}"
+CONTAINER_RUNTIME="${CONTAINER_RUNTIME:-docker}"
+
+echo "Building Argus Claude agent container image..."
+echo "Image: ${IMAGE_NAME}:${TAG}"
+
+${CONTAINER_RUNTIME} build -f Dockerfile.argus -t "${IMAGE_NAME}:${TAG}" .
+
+echo ""
+echo "Build complete: ${IMAGE_NAME}:${TAG}"
+echo "Set CONTAINER_IMAGE=${IMAGE_NAME}:${TAG} in your .env to use this image."

package/template/container/build.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Build the NanoClaw agent container image
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+IMAGE_NAME="nanoclaw-agent"
+TAG="${1:-latest}"
+CONTAINER_RUNTIME="${CONTAINER_RUNTIME:-docker}"
+
+echo "Building NanoClaw agent container image..."
+echo "Image: ${IMAGE_NAME}:${TAG}"
+
+${CONTAINER_RUNTIME} build -t "${IMAGE_NAME}:${TAG}" .
+
+echo ""
+echo "Build complete!"
+echo "Image: ${IMAGE_NAME}:${TAG}"
+echo ""
+echo "Test with:"
+echo "  echo '{\"prompt\":\"What is 2+2?\",\"groupFolder\":\"test\",\"chatJid\":\"test@g.us\",\"isMain\":false}' | ${CONTAINER_RUNTIME} run -i ${IMAGE_NAME}:${TAG}"

package/template/container/skills/agent-browser/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: agent-browser
+description: Browse the web for any task — research topics, read articles, interact with web apps, fill forms, take screenshots, extract data, and test web pages. Use whenever a browser would be useful, not just when the user explicitly asks.
+allowed-tools: Bash(agent-browser:*)
+---
+
+# Browser Automation with agent-browser
+
+## Quick start
+
+```bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+```
+
+## Core workflow
+
+1. Navigate: `agent-browser open <url>`
+2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+```
+
+### Snapshot (page analysis)
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+```
+
+### Interactions (use @refs from snapshot)
+
+```bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown option
+agent-browser scroll down 500     # Scroll page
+agent-browser upload @e1 file.pdf # Upload files
+```
+
+### Get information
+
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get count ".item"   # Count matching elements
+```
+
+### Screenshots & PDF
+
+```bash
+agent-browser screenshot          # Save to temp directory
+agent-browser screenshot path.png # Save to specific path
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+```
+
+### Wait
+
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait --load networkidle      # Wait for network idle
+```
+
+### Semantic locators (alternative to refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find placeholder "Search" type "query"
+```
+
+### Authentication with saved state
+
+```bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Cookies & Storage
+
+```bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get localStorage
+agent-browser storage local set k v       # Set value
+```
+
+### JavaScript
+
+```bash
+agent-browser eval "document.title"   # Run JavaScript
+```
+
+## Example: Form submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Example: Data extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e1  # Get product title
+agent-browser get attr @e2 href  # Get link URL
+agent-browser screenshot products.png
+```

package/template/container/skills/agent-status/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-status
+description: Dashboard of all registered NanoClaw agents — shows online/disabled status, last activity. Use when asked about agent health, who's online, or which agents exist.
+---
+
+# Agent Status Dashboard
+
+Generate a live status report of all NanoClaw agents.
+
+## Step 1 — Get registered agents from SQLite
+
+```bash
+python3 -c "
+import sqlite3, json
+db = sqlite3.connect('/workspace/project/store/messages.db')
+rows = db.execute('SELECT name, folder, is_main, requires_trigger FROM registered_groups ORDER BY name').fetchall()
+for r in rows:
+    print(json.dumps({'name': r[0], 'folder': r[1], 'is_main': bool(r[2]), 'requires_trigger': bool(r[3])}))
+db.close()
+"
+```
+
+## Step 2 — Check STATUS.md for each agent
+
+For each folder returned above:
+
+```bash
+cat /workspace/project/groups/<folder>/STATUS.md 2>/dev/null || echo "online"
+```
+
+STATUS.md contains either `online` or `disabled` with a reason.
+
+## Step 3 — Get last activity for each agent
+
+```bash
+python3 -c "
+import sqlite3, json
+db = sqlite3.connect('/workspace/project/store/messages.db')
+rows = db.execute('''
+    SELECT m.chat_jid, MAX(m.timestamp) as last_active
+    FROM messages m
+    GROUP BY m.chat_jid
+''').fetchall()
+for r in rows:
+    print(json.dumps({'jid': r[0], 'last_active': r[1]}))
+db.close()
+"
+```
+
+## Step 4 — Format the report
+
+Present as a clean Slack-formatted message:
+
+```
+*NanoClaw Agent Status*
+
+• *Argus Alert* — 🟢 online — last active: 2 hours ago
+• *Argus Deps* — 🟢 online — last active: 1 day ago
+• *Byte* — 🟢 online — last active: 30 min ago
+• *Jira Worker* — 🔴 disabled — reason: Too noisy, paused until Monday
+• *Ticket Creator* — 🟢 online — last active: 3 hours ago
+• *Global Claw* — 🟢 online (that's me)
+```
+
+Rules:
+- 🟢 = STATUS.md says `online` or file doesn't exist
+- 🔴 = STATUS.md says `disabled` — always show the reason
+- Last active: format as relative time (e.g. "2 hours ago", "3 days ago")
+- If no messages ever: "never"