@openparachute/agent 0.1.0

package/container/agent-runner/src/formatter.ts

@@ -0,0 +1,260 @@
+import { findByRouting } from './destinations.js';
+import type { MessageInRow } from './db/messages-in.js';
+import { TIMEZONE, formatLocalTime } from './timezone.js';
+
+/**
+ * Command categories for messages starting with '/'.
+ * - admin: sender must have an admin role in the central `user_roles` table
+ * - filtered: silently drop (mark completed without processing)
+ * - passthrough: pass raw to the agent (no XML wrapping)
+ * - none: not a command — format normally
+ */
+export type CommandCategory = 'admin' | 'filtered' | 'passthrough' | 'none';
+
+const ADMIN_COMMANDS = new Set(['/remote-control', '/clear', '/compact', '/context', '/cost', '/files']);
+const FILTERED_COMMANDS = new Set(['/help', '/login', '/logout', '/doctor', '/config', '/start']);
+
+export interface CommandInfo {
+  category: CommandCategory;
+  command: string; // the command name (e.g., '/clear')
+  text: string; // full original text
+  senderId: string | null;
+}
+
+/**
+ * Categorize a message as a command or not.
+ * Only applies to chat/chat-sdk messages.
+ *
+ * The extracted `senderId` is checked against the central DB's `user_roles`
+ * table on the host (the container itself doesn't enforce admin gating —
+ * that's the host's command gate, see src/command-gate.ts). User ids are
+ * stored in the namespaced form `<channel_type>:<raw>` (see src/db/users.ts).
+ * chat-sdk-bridge serializes `author.userId` as a raw platform id with no
+ * prefix, so we prefix it here. If the id already contains a `:` we assume
+ * it's pre-namespaced (non-chat-sdk adapters that populate `senderId`
+ * directly) and leave it alone.
+ */
+export function categorizeMessage(msg: MessageInRow): CommandInfo {
+  const content = parseContent(msg.content);
+  const text = (content.text || '').trim();
+  const senderId = extractSenderId(msg, content);
+
+  if (!text.startsWith('/')) {
+    return { category: 'none', command: '', text, senderId };
+  }
+
+  // Extract the command name (e.g., '/clear' from '/clear some args')
+  const command = text.split(/\s/)[0].toLowerCase();
+
+  if (ADMIN_COMMANDS.has(command)) {
+    return { category: 'admin', command, text, senderId };
+  }
+
+  if (FILTERED_COMMANDS.has(command)) {
+    return { category: 'filtered', command, text, senderId };
+  }
+
+  return { category: 'passthrough', command, text, senderId };
+}
+
+/**
+ * Narrow check for /clear — the only command the runner handles directly.
+ * All other command gating (filtered, admin) is done by the host router
+ * before messages reach the container.
+ */
+export function isClearCommand(msg: MessageInRow): boolean {
+  const content = parseContent(msg.content);
+  const text = (content.text || '').trim();
+  return text.toLowerCase().startsWith('/clear');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractSenderId(msg: MessageInRow, content: any): string | null {
+  const raw: string | null = content?.senderId || content?.author?.userId || null;
+  if (!raw) return null;
+  // Already namespaced (e.g. "telegram:123") — use as-is.
+  if (raw.includes(':')) return raw;
+  // Raw platform id from chat-sdk serialization — prefix with channel type.
+  if (!msg.channel_type) return raw;
+  return `${msg.channel_type}:${raw}`;
+}
+
+/**
+ * Routing context extracted from messages_in rows.
+ * Copied to messages_out by default so responses go back to the sender.
+ */
+export interface RoutingContext {
+  platformId: string | null;
+  channelType: string | null;
+  threadId: string | null;
+  inReplyTo: string | null;
+}
+
+/**
+ * Extract routing context from a batch of messages.
+ * Uses the first message's routing fields.
+ */
+export function extractRouting(messages: MessageInRow[]): RoutingContext {
+  const first = messages[0];
+  return {
+    platformId: first?.platform_id ?? null,
+    channelType: first?.channel_type ?? null,
+    threadId: first?.thread_id ?? null,
+    inReplyTo: first?.id ?? null,
+  };
+}
+
+/**
+ * Format a batch of messages_in rows into a prompt string.
+ *
+ * Prepends a `<context timezone="<IANA>" />` header so the agent always knows
+ * what timezone it's in — every timestamp it sees in message bodies is the
+ * user's local time, and every time it produces (schedules, suggests) should
+ * be interpreted as local time in that same zone. This header is v1 behavior
+ * (src/v1/router.ts:20-22); dropping it led to misinterpretations where the
+ * agent scheduled tasks for the wrong hour.
+ *
+ * Strips routing fields — the agent never sees platform_id, channel_type, thread_id.
+ */
+export function formatMessages(messages: MessageInRow[]): string {
+  const header = `<context timezone="${escapeXml(TIMEZONE)}" />\n`;
+  if (messages.length === 0) return header;
+
+  // Group by kind
+  const chatMessages = messages.filter((m) => m.kind === 'chat' || m.kind === 'chat-sdk');
+  const taskMessages = messages.filter((m) => m.kind === 'task');
+  const webhookMessages = messages.filter((m) => m.kind === 'webhook');
+  const systemMessages = messages.filter((m) => m.kind === 'system');
+
+  const parts: string[] = [];
+
+  if (chatMessages.length > 0) {
+    parts.push(formatChatMessages(chatMessages));
+  }
+  if (taskMessages.length > 0) {
+    parts.push(...taskMessages.map(formatTaskMessage));
+  }
+  if (webhookMessages.length > 0) {
+    parts.push(...webhookMessages.map(formatWebhookMessage));
+  }
+  if (systemMessages.length > 0) {
+    parts.push(...systemMessages.map(formatSystemMessage));
+  }
+
+  return header + parts.join('\n\n');
+}
+
+function formatChatMessages(messages: MessageInRow[]): string {
+  if (messages.length === 1) {
+    return formatSingleChat(messages[0]);
+  }
+
+  const lines = ['<messages>'];
+  for (const msg of messages) {
+    lines.push(formatSingleChat(msg));
+  }
+  lines.push('</messages>');
+  return lines.join('\n');
+}
+
+function formatSingleChat(msg: MessageInRow): string {
+  const content = parseContent(msg.content);
+  const sender = content.sender || content.author?.fullName || content.author?.userName || 'Unknown';
+  const time = formatLocalTime(msg.timestamp, TIMEZONE);
+  const text = content.text || '';
+  const idAttr = msg.seq != null ? ` id="${msg.seq}"` : '';
+  const replyAttr = content.replyTo?.id ? ` reply_to="${escapeXml(String(content.replyTo.id))}"` : '';
+  const replyPrefix = formatReplyContext(content.replyTo);
+  const attachmentsSuffix = formatAttachments(content.attachments);
+
+  // Look up the destination name for the origin (reverse map lookup).
+  // If not found, fall back to a raw channel:platform_id marker so nothing
+  // gets silently dropped — this should only happen if the destination was
+  // removed between when the message was received and when it's being processed.
+  const fromDest = findByRouting(msg.channel_type, msg.platform_id);
+  const fromAttr = fromDest
+    ? ` from="${escapeXml(fromDest.name)}"`
+    : msg.channel_type || msg.platform_id
+      ? ` from="unknown:${escapeXml(msg.channel_type || '')}:${escapeXml(msg.platform_id || '')}"`
+      : '';
+
+  return `<message${idAttr}${fromAttr} sender="${escapeXml(sender)}" time="${escapeXml(time)}"${replyAttr}>${replyPrefix}${escapeXml(text)}${attachmentsSuffix}</message>`;
+}
+
+function formatTaskMessage(msg: MessageInRow): string {
+  const content = parseContent(msg.content);
+  const parts = ['[SCHEDULED TASK]'];
+  if (content.scriptOutput) {
+    parts.push('', 'Script output:', JSON.stringify(content.scriptOutput, null, 2));
+  }
+  parts.push('', 'Instructions:', content.prompt || '');
+  return parts.join('\n');
+}
+
+function formatWebhookMessage(msg: MessageInRow): string {
+  const content = parseContent(msg.content);
+  const source = content.source || 'unknown';
+  const event = content.event || 'unknown';
+  return `[WEBHOOK: ${source}/${event}]\n\n${JSON.stringify(content.payload || content, null, 2)}`;
+}
+
+function formatSystemMessage(msg: MessageInRow): string {
+  const content = parseContent(msg.content);
+  return `[SYSTEM RESPONSE]\n\nAction: ${content.action || 'unknown'}\nStatus: ${content.status || 'unknown'}\nResult: ${JSON.stringify(content.result || null)}`;
+}
+
+/**
+ * Render the quoted original inside the <message> body.
+ *
+ * Matches v1 format (src/v1/router.ts:10-18): `<quoted_message from="X">Y</quoted_message>`.
+ * Requires BOTH sender and text — if only id is present the reply_to attribute
+ * on the parent <message> carries the link without an inline preview.
+ *
+ * No truncation here (v1 didn't truncate).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function formatReplyContext(replyTo: any): string {
+  if (!replyTo) return '';
+  const sender = replyTo.sender;
+  const text = replyTo.text;
+  if (!sender || !text) return '';
+  return `\n  <quoted_message from="${escapeXml(sender)}">${escapeXml(text)}</quoted_message>\n`;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function formatAttachments(attachments: any[] | undefined): string {
+  if (!Array.isArray(attachments) || attachments.length === 0) return '';
+  const parts = attachments.map((a) => {
+    const name = a.name || a.filename || 'attachment';
+    const type = a.type || 'file';
+    const localPath = a.localPath ? `/workspace/${a.localPath}` : '';
+    const url = a.url || '';
+    if (localPath) {
+      return `[${type}: ${escapeXml(name)} — saved to ${escapeXml(localPath)}]`;
+    }
+    return url ? `[${type}: ${escapeXml(name)} (${escapeXml(url)})]` : `[${type}: ${escapeXml(name)}]`;
+  });
+  return '\n' + parts.join('\n');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseContent(json: string): any {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return { text: json };
+  }
+}
+
+function escapeXml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/**
+ * Strip `<internal>...</internal>` blocks from agent output, then trim.
+ * Ported from v1 (src/v1/router.ts:25-27). Used to remove the agent's
+ * own scratchpad/reasoning before a reply goes out over a channel.
+ */
+export function stripInternalTags(text: string): string {
+  return text.replace(/<internal>[\s\S]*?<\/internal>/g, '').trim();
+}

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

@@ -0,0 +1,110 @@
+/**
+ * parachute-agent runner
+ *
+ * Runs inside a container. All IO goes through the session DB.
+ * No stdin, no stdout markers, no IPC files.
+ *
+ * Config is read from /workspace/agent/container.json (mounted RO).
+ * Only TZ comes from env.
+ *
+ * Mount structure:
+ *   /workspace/
+ *     inbound.db        ← host-owned session DB (container reads only)
+ *     outbound.db       ← container-owned session DB
+ *     .heartbeat        ← container touches for liveness detection
+ *     outbox/           ← outbound files
+ *     agent/            ← agent group folder (CLAUDE.md, container.json, working files)
+ *       container.json  ← per-group config (RO nested mount)
+ *     global/           ← shared global memory (RO)
+ *   /app/src/           ← shared agent-runner source (RO)
+ *   /app/skills/        ← shared skills (RO)
+ *   /home/node/.claude/ ← Claude SDK state + skill symlinks (RW)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { loadConfig } from './config.js';
+import { buildSystemPromptAddendum } from './destinations.js';
+// Providers barrel — each enabled provider self-registers on import.
+// Provider skills append imports to providers/index.ts.
+import './providers/index.js';
+import { createProvider, type ProviderName } from './providers/factory.js';
+import { runPollLoop } from './poll-loop.js';
+
+function log(msg: string): void {
+  console.error(`[agent-runner] ${msg}`);
+}
+
+const CWD = '/workspace/agent';
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const providerName = config.provider.toLowerCase() as ProviderName;
+
+  log(`Starting v2 agent-runner (provider: ${providerName})`);
+
+  // Runtime-generated system-prompt addendum: agent identity (name) plus
+  // the live destinations map. Everything else (capabilities, per-module
+  // instructions, per-channel formatting) is loaded by Claude Code from
+  // /workspace/agent/CLAUDE.md — the composed entry imports the shared
+  // base (/app/CLAUDE.md) and each enabled module's fragment. Per-group
+  // memory lives in /workspace/agent/CLAUDE.local.md (auto-loaded).
+  const instructions = buildSystemPromptAddendum(config.assistantName || undefined);
+
+  // Discover additional directories mounted at /workspace/extra/*
+  const additionalDirectories: string[] = [];
+  const extraBase = '/workspace/extra';
+  if (fs.existsSync(extraBase)) {
+    for (const entry of fs.readdirSync(extraBase)) {
+      const fullPath = path.join(extraBase, entry);
+      if (fs.statSync(fullPath).isDirectory()) {
+        additionalDirectories.push(fullPath);
+      }
+    }
+    if (additionalDirectories.length > 0) {
+      log(`Additional directories: ${additionalDirectories.join(', ')}`);
+    }
+  }
+
+  // MCP server path — bun runs TS directly; no tsc build step in-image.
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const mcpServerPath = path.join(__dirname, 'mcp-tools', 'index.ts');
+
+  // Build MCP servers config: parachute-agent built-in + any from container.json.
+  // Tools advertise as `mcp__parachute_agent__<verb>-<noun>` (the SDK's name
+  // mangle replaces non-alphanum with underscore). Renamed from `paraclaw` in
+  // 0.1.0; existing sessions need a restart to pick up the new prefix.
+  const mcpServers: Record<string, { command: string; args: string[]; env: Record<string, string> }> = {
+    'parachute-agent': {
+      command: 'bun',
+      args: ['run', mcpServerPath],
+      env: {},
+    },
+  };
+
+  for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+    mcpServers[name] = serverConfig;
+    log(`Additional MCP server: ${name} (${serverConfig.command})`);
+  }
+
+  const provider = createProvider(providerName, {
+    assistantName: config.assistantName || undefined,
+    mcpServers,
+    env: { ...process.env },
+    additionalDirectories: additionalDirectories.length > 0 ? additionalDirectories : undefined,
+  });
+
+  await runPollLoop({
+    provider,
+    providerName,
+    cwd: CWD,
+    systemContext: { instructions },
+  });
+}
+
+main().catch((err) => {
+  log(`Fatal error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/container/agent-runner/src/integration.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+
+import { initTestSessionDb, closeSessionDb, getInboundDb, getOutboundDb } from './db/connection.js';
+import { getUndeliveredMessages } from './db/messages-out.js';
+import { getPendingMessages } from './db/messages-in.js';
+import { MockProvider } from './providers/mock.js';
+import { runPollLoop } from './poll-loop.js';
+
+beforeEach(() => {
+  initTestSessionDb();
+  // Seed a destination so output parsing can resolve "discord-test" → routing
+  getInboundDb()
+    .prepare(
+      `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+       VALUES ('discord-test', 'Discord Test', 'channel', 'discord', 'chan-1', NULL)`,
+    )
+    .run();
+});
+
+afterEach(() => {
+  closeSessionDb();
+});
+
+function insertMessage(id: string, content: object, opts?: { platformId?: string; channelType?: string; threadId?: string }) {
+  getInboundDb()
+    .prepare(
+      `INSERT INTO messages_in (id, kind, timestamp, status, platform_id, channel_type, thread_id, content)
+       VALUES (?, 'chat', datetime('now'), 'pending', ?, ?, ?, ?)`,
+    )
+    .run(id, opts?.platformId ?? null, opts?.channelType ?? null, opts?.threadId ?? null, JSON.stringify(content));
+}
+
+describe('poll loop integration', () => {
+  it('should pick up a message, process it, and write a response', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'What is the meaning of life?' }, { platformId: 'chan-1', channelType: 'discord', threadId: 'thread-1' });
+
+    const provider = new MockProvider({}, () => '<message to="discord-test">42</message>');
+
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toBe('42');
+    expect(out[0].platform_id).toBe('chan-1');
+    expect(out[0].channel_type).toBe('discord');
+    expect(out[0].in_reply_to).toBe('m1');
+
+    // Input message should be acked (not pending)
+    const pending = getPendingMessages();
+    expect(pending).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('should process multiple messages in a batch', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'Hello' });
+    insertMessage('m2', { sender: 'Bob', text: 'World' });
+
+    const provider = new MockProvider({}, () => '<message to="discord-test">Got both messages</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toBe('Got both messages');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('should process messages arriving after loop starts', async () => {
+    const provider = new MockProvider({}, () => '<message to="discord-test">Processed</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 3000);
+
+    // Insert message after loop has started
+    await sleep(200);
+    insertMessage('m-late', { sender: 'Charlie', text: 'Late arrival' });
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out.length).toBeGreaterThanOrEqual(1);
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+// Helper: run poll loop until aborted or timeout
+async function runPollLoopWithTimeout(provider: MockProvider, signal: AbortSignal, timeoutMs: number): Promise<void> {
+  return Promise.race([
+    runPollLoop({
+      provider,
+      providerName: 'mock',
+      cwd: '/tmp',
+    }),
+    new Promise<void>((_, reject) => {
+      signal.addEventListener('abort', () => reject(new Error('aborted')));
+    }),
+    new Promise<void>((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+  ]);
+}
+
+async function waitFor(condition: () => boolean, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (!condition()) {
+    if (Date.now() - start > timeoutMs) throw new Error('waitFor timeout');
+    await sleep(50);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,26 @@
+## Companion and collaborator agents (`create_agent`)
+
+`mcp__parachute_agent__create_agent({ name, instructions })` spins up a new long-lived agent and wires it as a destination — bidirectional, so you can send it tasks and it can message you back.
+
+### How it works
+
+- Creates a new agent with its own container, workspace, and session. Your `instructions` string seeds the agent's `CLAUDE.local.md` — its starting role and personality.
+- The agent's `name` becomes a destination on both sides: you address it via `send_message({ to: "<name>", ... })`, and its replies arrive as inbound messages with `from="<name>"`.
+- Each agent has its own persistent workspace under `groups/<folder>/` — memory, conversation history, and notes all survive across sessions. This is a full standalone agent, not a stateless sub-query.
+- **Fire-and-forget:** the call returns immediately without waiting for the agent to confirm it's ready. Messages you send will queue until it's up.
+
+### When to use
+
+- **Companions** — a long-running presence that accumulates context over time: a `Researcher` tracking an ongoing inquiry, a `Calendar` agent managing scheduling, an assistant that knows your preferences and history.
+- **Collaborators** — a parallel specialist that works independently and reports back: a `Builder` handling code edits while you stay in conversation, a `Reviewer` running checks in the background.
+
+The right frame is: does this agent need its own memory and context that builds over time, or does it need to work independently without blocking your turn? Either is a good reason to spawn one.
+
+### When NOT to use
+
+- **One-off lookups or short tasks** — use the SDK `Agent` tool instead. It's stateless, spins up and completes in one shot, and leaves no persistent footprint.
+- **Work that finishes before the user's next message** — agents persist indefinitely. Don't create one for something you could do inline.
+
+### Writing good `instructions`
+
+Cover: the agent's role, who it takes tasks from (you, by name), how it should report back (on completion only? with milestones for long work?), and any domain-specific rules. Don't restate Parachute Agent base behavior — the shared base is already loaded on the agent's end.

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

@@ -0,0 +1,66 @@
+/**
+ * Agent management MCP tools: create_agent.
+ *
+ * send_to_agent was removed — sending to another agent is now just
+ * send_message(to="agent-name") since agents and channels share the
+ * unified destinations namespace.
+ *
+ * create_agent is admin-only. Non-admin containers never see this tool
+ * (see mcp-tools/index.ts). The host re-checks permission on receive.
+ */
+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 };
+}
+
+export const createAgent: McpToolDefinition = {
+  tool: {
+    name: 'create_agent',
+    description:
+      'Create a long-lived companion sub-agent (research assistant, task manager, specialist) — the name becomes your destination for it. Admin-only. Fire-and-forget.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        name: { type: 'string', description: 'Human-readable name (also becomes your destination name for this agent)' },
+        instructions: { type: 'string', description: 'CLAUDE.md content for the new agent (personality, role, instructions)' },
+      },
+      required: ['name'],
+    },
+  },
+  async handler(args) {
+    const name = args.name as string;
+    if (!name) return err('name is required');
+
+    const requestId = generateId();
+    writeMessageOut({
+      id: requestId,
+      kind: 'system',
+      content: JSON.stringify({
+        action: 'create_agent',
+        requestId,
+        name,
+        instructions: (args.instructions as string) || null,
+      }),
+    });
+
+    log(`create_agent: ${requestId} → "${name}"`);
+    return ok(`Creating agent "${name}". You will be notified when it is ready.`);
+  },
+};
+
+registerTools([createAgent]);

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

@@ -0,0 +1,27 @@
+## Sending messages
+
+Your final response is delivered via the `## Sending messages` rules in your runtime system prompt (single-destination: just write; multi-destination: use `<message to="name">...</message>` blocks). See that section for the current destination list.
+
+### Mid-turn updates (`send_message`)
+
+Use the `mcp__parachute_agent__send_message` tool to send a message while you're still working (before your final output). If you have one destination, `to` is optional; with multiple, specify it. Pace your updates to the length of the work:
+
+- **Short turn (≤2 quick tool calls):** Don't narrate. Output any response.
+- **Longer turn (multiple tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it, checking the logs now") so the user knows you got the message.
+- **Long-running turns (long-running tasks with many stages):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages.
+
+**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call.
+
+**Outcomes, not play-by-play.** When the turn is done, the final message should be about the result, not a transcript of what you did.
+
+### Sending files (`send_file`)
+
+Use `mcp__parachute_agent__send_file({ path, text?, filename?, to? })` to deliver a file from your workspace. `path` is absolute or relative to `/workspace/agent/`; `filename` overrides the display name shown in chat (defaults to the file's basename); `text` is an optional accompanying message. Use this for artifacts you produce (charts, PDFs, generated images, reports) rather than dumping contents into chat.
+
+### Reacting to messages (`add_reaction`)
+
+Use `mcp__parachute_agent__add_reaction({ messageId, emoji })` to react to a specific inbound message by its `#N` id — pass `messageId` as an integer (e.g. `22`, not `"22"`). Good for lightweight acknowledgment (`eyes` = seen, `white_check_mark` = done) when a full reply would be noise. `emoji` is the shortcode name (e.g. `thumbs_up`, `heart`), not the raw character.
+
+### Internal thoughts
+
+Wrap reasoning in `<internal>...</internal>` tags to mark it as scratchpad — logged but not sent.