@openparachute/agent 0.1.2 → 0.2.0

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

@@ -1,169 +0,0 @@
-/**
- * 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

@@ -1,40 +0,0 @@
-## 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

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

@@ -1,299 +0,0 @@
-/**
- * Scheduling MCP tools: schedule_task, list_tasks, cancel_task, pause_task, resume_task.
- *
- * With the two-DB split, the container cannot write to inbound.db (host-owned).
- * Scheduling operations are sent as system actions via messages_out — the host
- * reads them during delivery and applies the changes to inbound.db.
- */
-import { getInboundDb } from '../db/connection.js';
-import { writeMessageOut } from '../db/messages-out.js';
-import { getSessionRouting } from '../db/session-routing.js';
-import { TIMEZONE, parseZonedToUtc } from '../timezone.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 `task-${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 };
-}
-
-export const scheduleTask: McpToolDefinition = {
-  tool: {
-    name: 'schedule_task',
-    description:
-      `Schedule a one-shot or recurring task. The user's timezone is declared in the <context timezone="..."/> header of your prompt — interpret the user's "9pm" etc. in that zone. Cron expressions are interpreted in the user's timezone too.`,
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        prompt: { type: 'string', description: 'Task instructions/prompt' },
-        processAfter: {
-          type: 'string',
-          description:
-            `ISO 8601 timestamp for the first run. Accepts either UTC (ending in "Z" or "+00:00") or a naive local timestamp (no offset) which is interpreted in the user's timezone (e.g. "2026-01-15T21:00:00" = 9pm user-local). Prefer naive local.`,
-        },
-        recurrence: {
-          type: 'string',
-          description:
-            'Cron expression for recurring tasks (e.g., "0 9 * * 1-5" = weekdays at 9am user-local). Evaluated in the user\'s timezone.',
-        },
-        script: { type: 'string', description: 'Optional pre-agent script to run before processing' },
-      },
-      required: ['prompt', 'processAfter'],
-    },
-  },
-  async handler(args) {
-    const prompt = args.prompt as string;
-    const processAfterIn = args.processAfter as string;
-    if (!prompt || !processAfterIn) return err('prompt and processAfter are required');
-
-    let processAfter: string;
-    try {
-      const d = parseZonedToUtc(processAfterIn, TIMEZONE);
-      if (Number.isNaN(d.getTime())) return err(`invalid processAfter: ${processAfterIn}`);
-      processAfter = d.toISOString();
-    } catch {
-      return err(`invalid processAfter: ${processAfterIn}`);
-    }
-
-    const id = generateId();
-    const r = routing();
-    const recurrence = (args.recurrence as string) || null;
-    const script = (args.script as string) || null;
-
-    // Write as a system action — host will insert into inbound.db
-    writeMessageOut({
-      id,
-      kind: 'system',
-      platform_id: r.platform_id,
-      channel_type: r.channel_type,
-      thread_id: r.thread_id,
-      content: JSON.stringify({
-        action: 'schedule_task',
-        taskId: id,
-        prompt,
-        script,
-        processAfter,
-        recurrence,
-      }),
-    });
-
-    log(`schedule_task: ${id} at ${processAfter}${recurrence ? ` (recurring: ${recurrence})` : ''}`);
-    return ok(`Task scheduled (id: ${id}, runs at: ${processAfter}${recurrence ? `, recurrence: ${recurrence}` : ''})`);
-  },
-};
-
-export const listTasks: McpToolDefinition = {
-  tool: {
-    name: 'list_tasks',
-    description:
-      'List scheduled tasks. Returns one row per series — the live (pending or paused) occurrence. The id shown is the series id, which is what update_task / cancel_task / pause_task / resume_task expect.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        status: { type: 'string', description: 'Filter by status: pending or paused (default: both)' },
-      },
-    },
-  },
-  async handler(args) {
-    const status = args.status as string | undefined;
-    const db = getInboundDb();
-    // One row per series — the live (pending or paused) occurrence. Recurring
-    // tasks accumulate one completed row per firing plus one live follow-up;
-    // exposing the whole pile to the agent is noisy and confuses task identity
-    // ("which id do I cancel?"). The series_id is the stable handle.
-    //
-    // SQLite quirk: when MAX(seq) appears in the SELECT list of a GROUP BY
-    // query, the bare columns take values from the row that contains that max
-    // — that's how we pick "the latest live row per series" in one pass.
-    let rows;
-    if (status) {
-      rows = db
-        .prepare(
-          `SELECT series_id AS id, status, process_after, recurrence, content, MAX(seq) AS _seq
-             FROM messages_in
-            WHERE kind = 'task' AND status = ?
-            GROUP BY series_id
-            ORDER BY process_after ASC`,
-        )
-        .all(status);
-    } else {
-      rows = db
-        .prepare(
-          `SELECT series_id AS id, status, process_after, recurrence, content, MAX(seq) AS _seq
-             FROM messages_in
-            WHERE kind = 'task' AND status IN ('pending', 'paused')
-            GROUP BY series_id
-            ORDER BY process_after ASC`,
-        )
-        .all();
-    }
-
-    if ((rows as unknown[]).length === 0) return ok('No tasks found.');
-
-    const lines = (rows as Array<{ id: string; status: string; process_after: string | null; recurrence: string | null; content: string }>).map((r) => {
-      const content = JSON.parse(r.content);
-      const prompt = (content.prompt as string || '').slice(0, 80);
-      return `- ${r.id} [${r.status}] at=${r.process_after || 'now'} ${r.recurrence ? `recur=${r.recurrence} ` : ''}→ ${prompt}`;
-    });
-
-    return ok(lines.join('\n'));
-  },
-};
-
-export const cancelTask: McpToolDefinition = {
-  tool: {
-    name: 'cancel_task',
-    description: 'Cancel a scheduled task.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        taskId: { type: 'string', description: 'Task ID to cancel' },
-      },
-      required: ['taskId'],
-    },
-  },
-  async handler(args) {
-    const taskId = args.taskId as string;
-    if (!taskId) return err('taskId is required');
-
-    // Write as a system action — host will update inbound.db
-    writeMessageOut({
-      id: `sys-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-      kind: 'system',
-      content: JSON.stringify({ action: 'cancel_task', taskId }),
-    });
-
-    log(`cancel_task: ${taskId}`);
-    return ok(`Task cancellation requested: ${taskId}`);
-  },
-};
-
-export const pauseTask: McpToolDefinition = {
-  tool: {
-    name: 'pause_task',
-    description: 'Pause a scheduled task. It will not run until resumed.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        taskId: { type: 'string', description: 'Task ID to pause' },
-      },
-      required: ['taskId'],
-    },
-  },
-  async handler(args) {
-    const taskId = args.taskId as string;
-    if (!taskId) return err('taskId is required');
-
-    writeMessageOut({
-      id: `sys-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-      kind: 'system',
-      content: JSON.stringify({ action: 'pause_task', taskId }),
-    });
-
-    log(`pause_task: ${taskId}`);
-    return ok(`Task pause requested: ${taskId}`);
-  },
-};
-
-export const resumeTask: McpToolDefinition = {
-  tool: {
-    name: 'resume_task',
-    description: 'Resume a paused task.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        taskId: { type: 'string', description: 'Task ID to resume' },
-      },
-      required: ['taskId'],
-    },
-  },
-  async handler(args) {
-    const taskId = args.taskId as string;
-    if (!taskId) return err('taskId is required');
-
-    writeMessageOut({
-      id: `sys-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-      kind: 'system',
-      content: JSON.stringify({ action: 'resume_task', taskId }),
-    });
-
-    log(`resume_task: ${taskId}`);
-    return ok(`Task resume requested: ${taskId}`);
-  },
-};
-
-export const updateTask: McpToolDefinition = {
-  tool: {
-    name: 'update_task',
-    description:
-      'Update a scheduled task. Pass the series id from list_tasks. Any field omitted is left unchanged. Use this instead of cancel + reschedule when adjusting an existing task.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        taskId: { type: 'string', description: 'Series id of the task to update (as shown by list_tasks)' },
-        prompt: { type: 'string', description: 'New task prompt (optional)' },
-        recurrence: {
-          type: 'string',
-          description: 'New cron expression (optional). Pass empty string to clear and make the task one-shot.',
-        },
-        processAfter: {
-          type: 'string',
-          description:
-            `New ISO 8601 timestamp for the next run (optional). Accepts either UTC (ending in "Z" / "+00:00") or a naive local timestamp interpreted in the user's timezone.`,
-        },
-        script: {
-          type: 'string',
-          description: 'New pre-agent script (optional). Pass empty string to clear.',
-        },
-      },
-      required: ['taskId'],
-    },
-  },
-  async handler(args) {
-    const taskId = args.taskId as string;
-    if (!taskId) return err('taskId is required');
-
-    const update: Record<string, unknown> = { taskId };
-    if (typeof args.prompt === 'string') update.prompt = args.prompt;
-    if (typeof args.processAfter === 'string') {
-      try {
-        const d = parseZonedToUtc(args.processAfter, TIMEZONE);
-        if (Number.isNaN(d.getTime())) return err(`invalid processAfter: ${args.processAfter}`);
-        update.processAfter = d.toISOString();
-      } catch {
-        return err(`invalid processAfter: ${args.processAfter}`);
-      }
-    }
-    // Empty string clears recurrence/script; undefined leaves them as-is.
-    if (typeof args.recurrence === 'string') update.recurrence = args.recurrence === '' ? null : args.recurrence;
-    if (typeof args.script === 'string') update.script = args.script === '' ? null : args.script;
-
-    if (Object.keys(update).length === 1) return err('at least one field to update is required');
-
-    writeMessageOut({
-      id: `sys-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-      kind: 'system',
-      content: JSON.stringify({ action: 'update_task', ...update }),
-    });
-
-    log(`update_task: ${taskId}`);
-    return ok(`Task update requested: ${taskId}`);
-  },
-};
-
-registerTools([scheduleTask, listTasks, updateTask, cancelTask, pauseTask, resumeTask]);

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

@@ -1,25 +0,0 @@
-## Installing packages & tools
-
-To install packages that persist, use the self-modification tools:
-
-**`install_packages`** — request system (apt) or global npm packages. Requires admin approval.
-
-Example flow:
-```
-install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription" })
-# → Admin gets an approval card → approves
-```
-
-**When to use this vs workspace `pnpm install`:**
-- `pnpm install` if you only need it temporarily to do one task. Will not be available in subsequent truns.
-- `install_packages` persists for all future turns. Use especially if the user specifically asks you to add a capability
-
-### MCP servers (`add_mcp_server`)
-
-Use **`add_mcp_server`** to add an MCP server to your configuration. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.:
-
-```
-add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
-```
-
-Do not ask the user to give you credentials directly in chat. Credentials live in parachute-agent's local secret store and are injected into your container as env vars at spawn time. When an MCP server needs a credential, configure the env var name in `add_mcp_server` (e.g. `env: { GITHUB_TOKEN: "$GITHUB_TOKEN" }` references whatever the user named the secret) and ask the user to add the secret via parachute-agent's web UI at `/secrets`.

package/container/agent-runner/src/mcp-tools/self-mod.ts

@@ -1,120 +0,0 @@
-/**
- * Self-modification MCP tools: install_packages, add_mcp_server.
- *
- * Both are fire-and-forget — the tool writes a system action row and returns
- * immediately. The host processes the request (including admin approval)
- * and notifies the agent via a chat message when complete. Admin approval
- * is approval to apply the change: `install_packages` auto-rebuilds the
- * per-agent image and restarts the container; `add_mcp_server` just
- * updates `container.json` and restarts (bun runs TS directly — no build
- * step needed for a pure MCP wiring change).
- *
- * Package names are sanitized here at the tool boundary AND re-validated on
- * the host side (defense in depth).
- */
-import { writeMessageOut } from '../db/messages-out.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 };
-}
-
-const APT_RE = /^[a-z0-9][a-z0-9._+-]*$/;
-const NPM_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-const MAX_PACKAGES = 20;
-
-export const installPackages: McpToolDefinition = {
-  tool: {
-    name: 'install_packages',
-    description:
-      'Install apt and/or npm packages into YOUR per-agent container image. Requires admin approval; fire-and-forget. On approval, the image is rebuilt and the container is restarted automatically.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        apt: { type: 'array', items: { type: 'string' }, description: 'apt packages to install (names only, no version specs or flags)' },
-        npm: { type: 'array', items: { type: 'string' }, description: 'npm packages to install globally (names only, no version specs)' },
-        reason: { type: 'string', description: 'Why these packages are needed' },
-      },
-    },
-  },
-  async handler(args) {
-    const apt = (args.apt as string[]) || [];
-    const npm = (args.npm as string[]) || [];
-    if (apt.length === 0 && npm.length === 0) return err('At least one apt or npm package is required');
-    if (apt.length + npm.length > MAX_PACKAGES) return err(`Maximum ${MAX_PACKAGES} packages per request`);
-
-    const invalidApt = apt.find((p) => !APT_RE.test(p));
-    if (invalidApt) return err(`Invalid apt package name: "${invalidApt}". Only lowercase letters, digits, and ._+- allowed.`);
-    const invalidNpm = npm.find((p) => !NPM_RE.test(p));
-    if (invalidNpm) return err(`Invalid npm package name: "${invalidNpm}". No version specs or shell characters.`);
-
-    const requestId = generateId();
-    writeMessageOut({
-      id: requestId,
-      kind: 'system',
-      content: JSON.stringify({
-        action: 'install_packages',
-        apt,
-        npm,
-        reason: (args.reason as string) || '',
-      }),
-    });
-
-    log(`install_packages: ${requestId} → apt=[${apt.join(',')}] npm=[${npm.join(',')}]`);
-    return ok(`Package install request submitted. You will be notified when admin approves or rejects.`);
-  },
-};
-
-export const addMcpServer: McpToolDefinition = {
-  tool: {
-    name: 'add_mcp_server',
-    description:
-      'Wire an EXISTING third-party MCP server into YOUR per-agent runtime config — you must already know the exact `command` + `args` to invoke it (e.g. `npx @modelcontextprotocol/server-github`). Requires admin approval; fire-and-forget.',
-    inputSchema: {
-      type: 'object' as const,
-      properties: {
-        name: { type: 'string', description: 'MCP server name (unique identifier)' },
-        command: { type: 'string', description: 'Command to run the MCP server' },
-        args: { type: 'array', items: { type: 'string' }, description: 'Command arguments' },
-        env: { type: 'object', description: 'Environment variables for the server' },
-      },
-      required: ['name', 'command'],
-    },
-  },
-  async handler(args) {
-    const name = args.name as string;
-    const command = args.command as string;
-    if (!name || !command) return err('name and command are required');
-
-    const requestId = generateId();
-    writeMessageOut({
-      id: requestId,
-      kind: 'system',
-      content: JSON.stringify({
-        action: 'add_mcp_server',
-        name,
-        command,
-        args: (args.args as string[]) || [],
-        env: (args.env as Record<string, string>) || {},
-      }),
-    });
-
-    log(`add_mcp_server: ${requestId} → "${name}" (${command})`);
-    return ok(`MCP server request submitted. You will be notified when admin approves or rejects.`);
-  },
-};
-
-registerTools([installPackages, addMcpServer]);