@openparachute/agent 0.1.0

package/container/agent-runner/src/mcp-tools/core.ts

@@ -0,0 +1,262 @@
+/**
+ * Core MCP tools: send_message, send_file, edit_message, add_reaction.
+ *
+ * All outbound tools resolve destinations via the local destination map
+ * (see destinations.ts). Agents reference destinations by name; the map
+ * translates name → routing tuple. Permission enforcement happens on
+ * the host side in delivery.ts via the agent_destinations table.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { findByName, getAllDestinations } from '../destinations.js';
+import { getMessageIdBySeq, getRoutingBySeq, writeMessageOut } from '../db/messages-out.js';
+import { getSessionRouting } from '../db/session-routing.js';
+import { registerTools } from './server.js';
+import type { McpToolDefinition } from './types.js';
+
+function log(msg: string): void {
+  console.error(`[mcp-tools] ${msg}`);
+}
+
+function generateId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function ok(text: string) {
+  return { content: [{ type: 'text' as const, text }] };
+}
+
+function err(text: string) {
+  return { content: [{ type: 'text' as const, text: `Error: ${text}` }], isError: true };
+}
+
+function destinationList(): string {
+  const all = getAllDestinations();
+  if (all.length === 0) return '(none)';
+  return all.map((d) => d.name).join(', ');
+}
+
+/**
+ * Resolve a destination name to routing fields.
+ *
+ * If `to` is omitted, use the session's default reply routing (channel +
+ * thread the conversation is in) — the agent replies in place.
+ *
+ * If `to` is specified, look up the named destination. If it resolves to
+ * the same channel the session is bound to, the session's thread_id is
+ * preserved so replies land in the correct thread. Otherwise thread_id
+ * is null (a cross-destination send starts a new conversation).
+ */
+function resolveRouting(
+  to: string | undefined,
+):
+  | { channel_type: string; platform_id: string; thread_id: string | null; resolvedName: string }
+  | { error: string } {
+  if (!to) {
+    // Default: reply to whatever thread/channel this session is bound to.
+    const session = getSessionRouting();
+    if (session.channel_type && session.platform_id) {
+      return {
+        channel_type: session.channel_type,
+        platform_id: session.platform_id,
+        thread_id: session.thread_id,
+        resolvedName: '(current conversation)',
+      };
+    }
+    // No session routing (e.g., agent-shared or internal-only agent) —
+    // fall back to the legacy single-destination shortcut.
+    const all = getAllDestinations();
+    if (all.length === 0) return { error: 'No destinations configured.' };
+    if (all.length > 1) {
+      return {
+        error: `You have multiple destinations — specify "to". Options: ${all.map((d) => d.name).join(', ')}`,
+      };
+    }
+    to = all[0].name;
+  }
+  const dest = findByName(to);
+  if (!dest) return { error: `Unknown destination "${to}". Known: ${destinationList()}` };
+  if (dest.type === 'channel') {
+    // If the destination is the same channel the session is bound to,
+    // preserve the thread_id so replies land in the correct thread.
+    const session = getSessionRouting();
+    const threadId =
+      session.channel_type === dest.channelType && session.platform_id === dest.platformId
+        ? session.thread_id
+        : null;
+    return {
+      channel_type: dest.channelType!,
+      platform_id: dest.platformId!,
+      thread_id: threadId,
+      resolvedName: to,
+    };
+  }
+  return { channel_type: 'agent', platform_id: dest.agentGroupId!, thread_id: null, resolvedName: to };
+}
+
+export const sendMessage: McpToolDefinition = {
+  tool: {
+    name: 'send_message',
+    description:
+      'Send a message to a named destination. If you have only one destination, you can omit `to`.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        to: { type: 'string', description: 'Destination name (e.g., "family", "worker-1"). Optional if you have only one destination.' },
+        text: { type: 'string', description: 'Message content' },
+      },
+      required: ['text'],
+    },
+  },
+  async handler(args) {
+    const text = args.text as string;
+    if (!text) return err('text is required');
+
+    const routing = resolveRouting(args.to as string | undefined);
+    if ('error' in routing) return err(routing.error);
+
+    const id = generateId();
+    const seq = writeMessageOut({
+      id,
+      kind: 'chat',
+      platform_id: routing.platform_id,
+      channel_type: routing.channel_type,
+      thread_id: routing.thread_id,
+      content: JSON.stringify({ text }),
+    });
+
+    log(`send_message: #${seq} → ${routing.resolvedName}`);
+    return ok(`Message sent to ${routing.resolvedName} (id: ${seq})`);
+  },
+};
+
+export const sendFile: McpToolDefinition = {
+  tool: {
+    name: 'send_file',
+    description: 'Send a file to a named destination. If you have only one destination, you can omit `to`.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        to: { type: 'string', description: 'Destination name. Optional if you have only one destination.' },
+        path: { type: 'string', description: 'File path (relative to /workspace/agent/ or absolute)' },
+        text: { type: 'string', description: 'Optional accompanying message' },
+        filename: { type: 'string', description: 'Display name (default: basename of path)' },
+      },
+      required: ['path'],
+    },
+  },
+  async handler(args) {
+    const filePath = args.path as string;
+    if (!filePath) return err('path is required');
+
+    const routing = resolveRouting(args.to as string | undefined);
+    if ('error' in routing) return err(routing.error);
+
+    const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve('/workspace/agent', filePath);
+    if (!fs.existsSync(resolvedPath)) return err(`File not found: ${filePath}`);
+
+    const id = generateId();
+    const filename = (args.filename as string) || path.basename(resolvedPath);
+
+    const outboxDir = path.join('/workspace/outbox', id);
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.copyFileSync(resolvedPath, path.join(outboxDir, filename));
+
+    writeMessageOut({
+      id,
+      kind: 'chat',
+      platform_id: routing.platform_id,
+      channel_type: routing.channel_type,
+      thread_id: routing.thread_id,
+      content: JSON.stringify({ text: (args.text as string) || '', files: [filename] }),
+    });
+
+    log(`send_file: ${id} → ${routing.resolvedName} (${filename})`);
+    return ok(`File sent to ${routing.resolvedName} (id: ${id}, filename: ${filename})`);
+  },
+};
+
+export const editMessage: McpToolDefinition = {
+  tool: {
+    name: 'edit_message',
+    description: 'Edit a previously sent message. Targets the same destination the original message was sent to.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        messageId: { type: 'integer', description: 'Message ID (the numeric id shown in messages)' },
+        text: { type: 'string', description: 'New message content' },
+      },
+      required: ['messageId', 'text'],
+    },
+  },
+  async handler(args) {
+    const seq = Number(args.messageId);
+    const text = args.text as string;
+    if (!seq || !text) return err('messageId and text are required');
+
+    const platformId = getMessageIdBySeq(seq);
+    if (!platformId) return err(`Message #${seq} not found`);
+
+    const routing = getRoutingBySeq(seq);
+    if (!routing || !routing.channel_type || !routing.platform_id) {
+      return err(`Cannot determine destination for message #${seq}`);
+    }
+
+    const id = generateId();
+    writeMessageOut({
+      id,
+      kind: 'chat',
+      platform_id: routing.platform_id,
+      channel_type: routing.channel_type,
+      thread_id: routing.thread_id,
+      content: JSON.stringify({ operation: 'edit', messageId: platformId, text }),
+    });
+
+    log(`edit_message: #${seq} → ${platformId}`);
+    return ok(`Message edit queued for #${seq}`);
+  },
+};
+
+export const addReaction: McpToolDefinition = {
+  tool: {
+    name: 'add_reaction',
+    description: 'Add an emoji reaction to a message.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        messageId: { type: 'integer', description: 'Message ID (the numeric id shown in messages)' },
+        emoji: { type: 'string', description: 'Emoji name (e.g., thumbs_up, heart, check)' },
+      },
+      required: ['messageId', 'emoji'],
+    },
+  },
+  async handler(args) {
+    const seq = Number(args.messageId);
+    const emoji = args.emoji as string;
+    if (!seq || !emoji) return err('messageId and emoji are required');
+
+    const platformId = getMessageIdBySeq(seq);
+    if (!platformId) return err(`Message #${seq} not found`);
+
+    const routing = getRoutingBySeq(seq);
+    if (!routing || !routing.channel_type || !routing.platform_id) {
+      return err(`Cannot determine destination for message #${seq}`);
+    }
+
+    const id = generateId();
+    writeMessageOut({
+      id,
+      kind: 'chat',
+      platform_id: routing.platform_id,
+      channel_type: routing.channel_type,
+      thread_id: routing.thread_id,
+      content: JSON.stringify({ operation: 'reaction', messageId: platformId, emoji }),
+    });
+
+    log(`add_reaction: #${seq} → ${emoji} on ${platformId}`);
+    return ok(`Reaction queued for #${seq}`);
+  },
+};
+
+registerTools([sendMessage, sendFile, editMessage, addReaction]);

package/container/agent-runner/src/mcp-tools/index.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP tools barrel — imports each tool module for its side-effect
+ * `registerTools([...])` call, then starts the MCP server.
+ *
+ * Adding a new tool module: create the file, call `registerTools([...])`
+ * at module scope, and append the import here. No central list.
+ */
+import './core.js';
+import './scheduling.js';
+import './interactive.js';
+import './agents.js';
+import './self-mod.js';
+import { startMcpServer } from './server.js';
+
+function log(msg: string): void {
+  console.error(`[mcp-tools] ${msg}`);
+}
+
+startMcpServer().catch((err) => {
+  log(`MCP server error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/container/agent-runner/src/mcp-tools/interactive.instructions.md

@@ -0,0 +1,22 @@
+## Interactive prompts
+
+The two tools here solve different problems: `ask_user_question` forces a decision and waits for it; `send_card` displays structured content and moves on.
+
+### Asking a multiple-choice question (`ask_user_question`)
+
+`mcp__parachute_agent__ask_user_question({ title, question, options, timeout? })` presents the user with a set of choices and **blocks your turn** until they tap one or the timeout expires (default: 300 seconds). Returns their chosen value.
+
+`options` can be plain strings or `{ label, selectedLabel?, value? }` objects:
+- `label` — the button text shown before selection
+- `selectedLabel` — the text shown on the button *after* selection (useful for confirmations, e.g. `"✓ Confirmed"`)
+- `value` — the string returned to you when that option is chosen (defaults to `label`)
+
+Use this when you genuinely cannot proceed without a decision. For free-text input, send a normal message and wait for their reply — don't reach for this tool.
+
+### Structured cards (`send_card`)
+
+`mcp__parachute_agent__send_card({ card, fallbackText? })` renders a structured card and **returns immediately** — it does not pause your turn or collect a response.
+
+`card` supports: `title`, `description`, `children` (nested text or content blocks), and `actions` (buttons). `fallbackText` is sent as a plain message on platforms without card support.
+
+Use this for presenting information in a cleaner format than prose: summaries, options the user can read (but you're not waiting on), or results with contextual buttons. If you need the user to actually *choose* something and return a value, use `ask_user_question` instead.

package/container/agent-runner/src/mcp-tools/interactive.ts

@@ -0,0 +1,169 @@
+/**
+ * Interactive MCP tools: ask_user_question, send_card.
+ *
+ * ask_user_question is a blocking tool call — it writes a messages_out row
+ * with a question card, then polls messages_in for the response.
+ */
+import { findQuestionResponse, markCompleted } from '../db/messages-in.js';
+import { writeMessageOut } from '../db/messages-out.js';
+import { getSessionRouting } from '../db/session-routing.js';
+import { registerTools } from './server.js';
+import type { McpToolDefinition } from './types.js';
+
+function log(msg: string): void {
+  console.error(`[mcp-tools] ${msg}`);
+}
+
+function generateId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function routing() {
+  return getSessionRouting();
+}
+
+function ok(text: string) {
+  return { content: [{ type: 'text' as const, text }] };
+}
+
+function err(text: string) {
+  return { content: [{ type: 'text' as const, text: `Error: ${text}` }], isError: true };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const askUserQuestion: McpToolDefinition = {
+  tool: {
+    name: 'ask_user_question',
+    description:
+      'Ask the user a multiple-choice question and wait for their response. This is a blocking call — execution pauses until the user responds or the timeout expires. Provide a short card title (e.g. "Confirm deletion") and an array of options — each option may be a plain string (used as both button label and result value) or an object { label, selectedLabel?, value? } where selectedLabel is the text shown on the card after the user clicks.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        title: { type: 'string', description: 'Short card title shown above the question' },
+        question: { type: 'string', description: 'The question to ask' },
+        options: {
+          type: 'array',
+          items: {
+            oneOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                properties: {
+                  label: { type: 'string' },
+                  selectedLabel: { type: 'string' },
+                  value: { type: 'string' },
+                },
+                required: ['label'],
+              },
+            ],
+          },
+          description: 'Options for the user to choose from (string or {label, selectedLabel?, value?})',
+        },
+        timeout: { type: 'number', description: 'Timeout in seconds (default: 300)' },
+      },
+      required: ['title', 'question', 'options'],
+    },
+  },
+  async handler(args) {
+    const title = args.title as string;
+    const question = args.question as string;
+    const rawOptions = args.options as unknown[];
+    const timeout = ((args.timeout as number) || 300) * 1000;
+    if (!title || !question || !rawOptions?.length) {
+      return err('title, question, and options are required');
+    }
+
+    const options = rawOptions.map((o) => {
+      if (typeof o === 'string') return { label: o, selectedLabel: o, value: o };
+      const obj = o as { label: string; selectedLabel?: string; value?: string };
+      return {
+        label: obj.label,
+        selectedLabel: obj.selectedLabel ?? obj.label,
+        value: obj.value ?? obj.label,
+      };
+    });
+
+    const questionId = generateId();
+    const r = routing();
+
+    // Write question card to outbound.db
+    writeMessageOut({
+      id: questionId,
+      kind: 'chat-sdk',
+      platform_id: r.platform_id,
+      channel_type: r.channel_type,
+      thread_id: r.thread_id,
+      content: JSON.stringify({
+        type: 'ask_question',
+        questionId,
+        title,
+        question,
+        options,
+      }),
+    });
+
+    log(`ask_user_question: ${questionId} → "${question}" [${options.join(', ')}]`);
+
+    // Poll for response in inbound.db (host writes the response there)
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const response = findQuestionResponse(questionId);
+
+      if (response) {
+        const parsed = JSON.parse(response.content);
+        // Mark the response as completed via processing_ack (outbound.db)
+        markCompleted([response.id]);
+
+        log(`ask_user_question response: ${questionId} → ${parsed.selectedOption}`);
+        return ok(parsed.selectedOption);
+      }
+
+      await sleep(1000);
+    }
+
+    log(`ask_user_question timeout: ${questionId}`);
+    return err(`Question timed out after ${timeout / 1000}s`);
+  },
+};
+
+export const sendCard: McpToolDefinition = {
+  tool: {
+    name: 'send_card',
+    description: 'Send a structured card (interactive or display-only) to the current conversation.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        card: {
+          type: 'object',
+          description: 'Card structure with title, description, and optional children/actions',
+        },
+        fallbackText: { type: 'string', description: 'Text fallback for platforms without card support' },
+      },
+      required: ['card'],
+    },
+  },
+  async handler(args) {
+    const card = args.card as Record<string, unknown>;
+    if (!card) return err('card is required');
+
+    const id = generateId();
+    const r = routing();
+
+    writeMessageOut({
+      id,
+      kind: 'chat-sdk',
+      platform_id: r.platform_id,
+      channel_type: r.channel_type,
+      thread_id: r.thread_id,
+      content: JSON.stringify({ type: 'card', card, fallbackText: (args.fallbackText as string) || '' }),
+    });
+
+    log(`send_card: ${id}`);
+    return ok(`Card sent (id: ${id})`);
+  },
+};
+
+registerTools([askUserQuestion, sendCard]);

package/container/agent-runner/src/mcp-tools/scheduling.instructions.md

@@ -0,0 +1,40 @@
+## Task scheduling (`schedule_task`)
+
+For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below.
+
+To inspect or change existing tasks, use `list_tasks` (returns one row per series with the stable id) and `update_task` / `cancel_task` / `pause_task` / `resume_task`. Prefer `update_task` over cancel + reschedule.
+
+Frequent recurring scheduled tasks — more than a few times a day — consume API credits and can risk account restrictions. You can add a `script` that runs first, and you will only be called when the check passes.
+
+### How it works
+
+1. Provide a bash `script` alongside the `prompt` when scheduling
+2. When the task fires, the script runs first
+3. Script returns: `{ "wakeAgent": true/false, "data": {...} }`
+4. If `wakeAgent: false` — nothing happens, task waits for next run
+5. If `wakeAgent: true` — claude receives the script's data + prompt and handles
+
+### Always test your script first
+
+Before scheduling, run the script directly to verify it works:
+
+```bash
+bash -c 'node --input-type=module -e "
+  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
+  const prs = await r.json();
+  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
+"'
+```
+
+### When NOT to use scripts
+
+If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt. Do not attempt to do things like sentiment analysis or advanced nlp in scripts.
+
+### Frequent task guidance
+
+If a user wants a task to run more than a few times a day and a script can't be used:
+
+- Explain that each time the task fires it uses API credits and risks rate limits
+- Suggest adjusting the task requirements in a way that will allow you to use a script
+- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
+- Help the user find the minimum viable frequency