@openparachute/agent 0.1.0

package/src/channels/cli.ts

@@ -0,0 +1,276 @@
+/**
+ * CLI channel — talk to your agent from a local terminal via Unix socket.
+ *
+ * Always-on, zero-credentials channel that ships with main. The daemon
+ * listens on `data/cli.sock`; the `scripts/chat.ts` client connects, writes
+ * a JSON line per message, reads JSON lines back. The channel plumbs into
+ * the normal router/delivery path like any other adapter — `/clear` and
+ * other session-level commands work identically.
+ *
+ * Wire format: one JSON object per line.
+ *
+ *   Client → server:
+ *     { "text": "user message" }                          # default — talk to cli/local
+ *     { "text": "...", "to": {"channelType": "discord",
+ *                             "platformId": "discord:@me:149...",
+ *                             "threadId": null} }         # route to a specific mg
+ *     { "text": "...", "to": {...}, "reply_to": {...} }   # + redirect replies
+ *   Server → client:
+ *     { "text": "agent reply" }
+ *
+ * The `to` and `reply_to` addressing is how admin transports (the bootstrap
+ * script) inject messages targeting any wired channel. `reply_to` is a
+ * router-layer concept — agents cannot set it; it is carried only on
+ * inbound events from CLI clients that hold operator privilege (the socket
+ * is chmod 0600, so "connected to this socket" ≈ "is the owner").
+ *
+ * Single-client chat semantics: one connected terminal at a time. A second
+ * "chat" connection closes the first with a "superseded" notice. Admin
+ * route-opcode connections (`to` set) are one-shot and do NOT evict an
+ * active chat client.
+ *
+ * deliver() silently no-ops when no client is connected. The outbound row
+ * is already in outbound.db, so the message isn't lost — it just doesn't
+ * reach this run's terminal. Reconnect to see subsequent replies.
+ */
+import fs from 'fs';
+import net from 'net';
+import path from 'path';
+
+import { DATA_DIR } from '../config.js';
+import { log } from '../log.js';
+import type { ChannelAdapter, ChannelSetup, DeliveryAddress, InboundEvent, OutboundMessage } from './adapter.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+const PLATFORM_ID = 'local';
+
+function socketPath(): string {
+  return path.join(DATA_DIR, 'cli.sock');
+}
+
+function createAdapter(): ChannelAdapter {
+  let server: net.Server | null = null;
+  let client: net.Socket | null = null;
+
+  const adapter: ChannelAdapter = {
+    name: 'cli',
+    channelType: 'cli',
+    supportsThreads: false,
+
+    async setup(config: ChannelSetup): Promise<void> {
+      const sock = socketPath();
+
+      // Stale socket cleanup: a previous run that crashed may have left the
+      // file behind, and net.createServer refuses to bind to an existing path.
+      try {
+        fs.unlinkSync(sock);
+      } catch (err) {
+        const e = err as NodeJS.ErrnoException;
+        if (e.code !== 'ENOENT') {
+          log.warn('Failed to unlink stale CLI socket (will try to bind anyway)', { sock, err });
+        }
+      }
+
+      server = net.createServer((socket) => handleConnection(socket, config));
+      await new Promise<void>((resolve, reject) => {
+        server!.once('error', reject);
+        server!.listen(sock, () => {
+          // Tighten perms so only the owner can connect. Unix socket files
+          // obey filesystem perms — 0700 on the socket means other local
+          // users can't send into this agent.
+          try {
+            fs.chmodSync(sock, 0o600);
+          } catch (err) {
+            log.warn('Failed to chmod CLI socket (continuing)', { sock, err });
+          }
+          log.info('CLI channel listening', { sock });
+          resolve();
+        });
+      });
+    },
+
+    async teardown(): Promise<void> {
+      if (client) {
+        try {
+          client.end();
+        } catch {
+          // swallow — teardown is best-effort
+        }
+        client = null;
+      }
+      if (server) {
+        await new Promise<void>((resolve) => {
+          server!.close(() => resolve());
+        });
+        server = null;
+      }
+      // Remove the socket file so a relaunch doesn't trip over it.
+      try {
+        fs.unlinkSync(socketPath());
+      } catch {
+        // swallow
+      }
+    },
+
+    isConnected(): boolean {
+      return server !== null;
+    },
+
+    async deliver(platformId, _threadId, message: OutboundMessage): Promise<string | undefined> {
+      if (platformId !== PLATFORM_ID) return undefined;
+      if (!client) {
+        // No live terminal — outbound row is already persisted, so this
+        // isn't a data loss. User will see it on the next connect cycle
+        // (or never, if we don't add scroll-back). Not worth throwing.
+        return undefined;
+      }
+      const text = extractText(message);
+      if (text === null) return undefined;
+      try {
+        client.write(JSON.stringify({ text }) + '\n');
+      } catch (err) {
+        log.warn('Failed to write to CLI client', { err });
+      }
+      return undefined;
+    },
+  };
+
+  function handleConnection(socket: net.Socket, config: ChannelSetup): void {
+    // Defer the chat-slot swap until we see the first line — if it turns out
+    // to be a routed (`to`-bearing) one-shot, we leave the existing chat
+    // client in place. Only plain chat connections participate in supersede.
+    let claimedChatSlot = false;
+
+    const claimChatSlot = () => {
+      if (claimedChatSlot) return;
+      claimedChatSlot = true;
+      if (client && client !== socket) {
+        try {
+          client.write(JSON.stringify({ text: '[superseded by a newer client]' }) + '\n');
+          client.end();
+        } catch {
+          // swallow
+        }
+      }
+      client = socket;
+      log.info('CLI client connected');
+    };
+
+    let buffer = '';
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      let idx: number;
+      while ((idx = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!line) continue;
+        void handleLine(line, config, claimChatSlot);
+      }
+    });
+
+    socket.on('close', () => {
+      if (client === socket) client = null;
+      if (claimedChatSlot) log.info('CLI client disconnected');
+    });
+
+    socket.on('error', (err) => {
+      log.warn('CLI client socket error', { err });
+    });
+  }
+
+  async function handleLine(line: string, config: ChannelSetup, claimChatSlot: () => void): Promise<void> {
+    let payload: {
+      text?: unknown;
+      to?: unknown;
+      reply_to?: unknown;
+      sender?: unknown;
+      senderId?: unknown;
+    };
+    try {
+      payload = JSON.parse(line);
+    } catch (err) {
+      log.warn('CLI: ignoring non-JSON line from client', { line });
+      return;
+    }
+    if (typeof payload.text !== 'string' || payload.text.length === 0) return;
+
+    const to = parseAddress(payload.to);
+    const replyTo = parseAddress(payload.reply_to);
+
+    if (to) {
+      // Routed message — admin transport. Build a full InboundEvent targeting
+      // `to`'s channel/platform, and let `reply_to` (if any) redirect replies.
+      // Does NOT claim the chat slot, so an active terminal chat isn't evicted.
+      const event: InboundEvent = {
+        channelType: to.channelType,
+        platformId: to.platformId,
+        threadId: to.threadId,
+        message: {
+          id: `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          kind: 'chat',
+          timestamp: new Date().toISOString(),
+          content: JSON.stringify({
+            text: payload.text,
+            sender: typeof payload.sender === 'string' ? payload.sender : 'cli',
+            senderId: typeof payload.senderId === 'string' ? payload.senderId : `cli:${PLATFORM_ID}`,
+          }),
+        },
+        replyTo: replyTo ?? undefined,
+      };
+      try {
+        await config.onInboundEvent(event);
+      } catch (err) {
+        log.error('CLI: onInboundEvent threw', { err });
+      }
+      return;
+    }
+
+    // Plain chat — claim the slot (evicting any prior client) and route via
+    // the standard onInbound path (adapter injects its own channelType).
+    claimChatSlot();
+    try {
+      await config.onInbound(PLATFORM_ID, null, {
+        id: `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        kind: 'chat',
+        timestamp: new Date().toISOString(),
+        content: {
+          text: payload.text,
+          sender: 'cli',
+          senderId: `cli:${PLATFORM_ID}`,
+        },
+      });
+    } catch (err) {
+      log.error('CLI: onInbound threw', { err });
+    }
+  }
+
+  function parseAddress(raw: unknown): DeliveryAddress | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const obj = raw as Record<string, unknown>;
+    if (typeof obj.channelType !== 'string' || typeof obj.platformId !== 'string') return null;
+    const threadId =
+      obj.threadId === null || obj.threadId === undefined
+        ? null
+        : typeof obj.threadId === 'string'
+          ? obj.threadId
+          : null;
+    return {
+      channelType: obj.channelType,
+      platformId: obj.platformId,
+      threadId,
+    };
+  }
+
+  return adapter;
+}
+
+function extractText(message: OutboundMessage): string | null {
+  const content = message.content as Record<string, unknown> | string | undefined;
+  if (typeof content === 'string') return content;
+  if (content && typeof content === 'object' && typeof content.text === 'string') {
+    return content.text;
+  }
+  return null;
+}
+
+registerChannelAdapter('cli', { factory: createAdapter });

package/src/channels/discord.ts

@@ -0,0 +1,90 @@
+/**
+ * Discord channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createDiscordAdapter } from '@chat-adapter/discord';
+
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+import type { ChannelAdapter } from './adapter.js';
+import { createChatSdkBridge, type ReplyContext } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractReplyContext(raw: Record<string, any>): ReplyContext | null {
+  if (!raw.referenced_message) return null;
+  const reply = raw.referenced_message;
+  return {
+    text: reply.content || '',
+    sender: reply.author?.global_name || reply.author?.username || 'Unknown',
+  };
+}
+
+export interface DiscordSpawnInput {
+  botToken: string;
+  applicationId: string;
+  publicKey?: string;
+}
+
+/**
+ * Build (but don't `setup()`) a Discord channel adapter for the given bot
+ * credentials. Discord doesn't expose a getMe-equivalent for the bot user
+ * itself, so the bot's identity (`applicationId`) must be passed in by the
+ * caller — read from `.env`'s `DISCORD_APPLICATION_ID` for the primary
+ * adapter, or from the secret/operator input for dynamic per-bot adds.
+ *
+ * Used by:
+ *   - the channel-registry's startup factory below (single bot via `.env`)
+ *   - `registerBotAdapter('discord', { ... })` (dynamic per-bot adds)
+ *   - the secrets-backed startup scan
+ */
+export function spawnDiscordAdapter(input: DiscordSpawnInput): ChannelAdapter {
+  const { botToken, applicationId, publicKey } = input;
+  const botId = applicationId;
+  const discordAdapter = createDiscordAdapter({
+    botToken,
+    publicKey,
+    applicationId,
+  });
+  const bridge = createChatSdkBridge({
+    adapter: discordAdapter,
+    botId,
+    concurrency: 'concurrent',
+    botToken,
+    extractReplyContext,
+    supportsThreads: true,
+  });
+  return { ...bridge, botId };
+}
+
+registerChannelAdapter('discord', {
+  factory: () => {
+    const env = readEnvFile(['DISCORD_BOT_TOKEN', 'DISCORD_PUBLIC_KEY', 'DISCORD_APPLICATION_ID']);
+    if (!env.DISCORD_BOT_TOKEN) return null;
+    if (!env.DISCORD_APPLICATION_ID) return null;
+    return spawnDiscordAdapter({
+      botToken: env.DISCORD_BOT_TOKEN,
+      applicationId: env.DISCORD_APPLICATION_ID,
+      publicKey: env.DISCORD_PUBLIC_KEY,
+    });
+  },
+  /**
+   * Discord has no `getMe`-equivalent, so the applicationId must come from
+   * somewhere. Convention: `CHANNEL_BOT_TOKEN:discord:<applicationId>` —
+   * the trailing segment IS the applicationId. Public key is webhook-only
+   * (interaction mode); polling-mode bots leave it undefined.
+   */
+  spawnFromSecret: async (secretName, secretValue) => {
+    const applicationId = secretName.split(':').pop();
+    if (!applicationId) {
+      log.error('Discord spawnFromSecret got malformed secret name', { secretName });
+      return null;
+    }
+    try {
+      return spawnDiscordAdapter({ botToken: secretValue, applicationId });
+    } catch (err) {
+      log.error('Discord spawnFromSecret failed', { secretName, err });
+      return null;
+    }
+  },
+});

package/src/channels/index.ts

@@ -0,0 +1,17 @@
+// Channel self-registration barrel.
+// Each import triggers the channel module's registerChannelAdapter() call.
+//
+// Trunk now ships three permanent channels:
+//   - cli — always-on local-terminal channel (no credentials)
+//   - discord — Chat-SDK bridge, gated on DISCORD_BOT_TOKEN
+//   - telegram — Chat-SDK bridge with the pairing interceptor, gated on
+//     TELEGRAM_BOT_TOKEN
+//
+// Each adapter is dormant until its env credentials are present, so an
+// install with no credentials still boots cleanly. Additional channels
+// (Slack, WhatsApp, etc.) remain skill-installed from the `channels`
+// branch and append their import below.
+
+import './cli.js';
+import './discord.js';
+import './telegram.js';

package/src/channels/telegram-markdown-sanitize.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeTelegramLegacyMarkdown } from './telegram-markdown-sanitize.js';
+
+describe('sanitizeTelegramLegacyMarkdown', () => {
+  it('downgrades CommonMark **bold** to legacy *bold*', () => {
+    expect(sanitizeTelegramLegacyMarkdown('**Host path**')).toBe('*Host path*');
+  });
+
+  it('downgrades CommonMark __bold__ to legacy _italic_', () => {
+    expect(sanitizeTelegramLegacyMarkdown('__label__')).toBe('_label_');
+  });
+
+  it('leaves balanced legacy *bold* and _italic_ alone', () => {
+    expect(sanitizeTelegramLegacyMarkdown('a *b* c _d_ e')).toBe('a *b* c _d_ e');
+  });
+
+  it('preserves inline code spans untouched', () => {
+    const input = 'see `file_name.py` and `**not bold**` here';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('preserves fenced code blocks untouched', () => {
+    const input = '```\nfoo_bar **baz**\n```';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('strips formatting chars on odd delimiter count (unbalanced *)', () => {
+    expect(sanitizeTelegramLegacyMarkdown('a * b *c*')).toBe('a  b c');
+  });
+
+  it('strips formatting chars on odd delimiter count (unbalanced _)', () => {
+    expect(sanitizeTelegramLegacyMarkdown('file_name has _one italic_')).toBe('filename has one italic');
+  });
+
+  it('strips brackets when unbalanced', () => {
+    expect(sanitizeTelegramLegacyMarkdown('see [docs here')).toBe('see docs here');
+  });
+
+  it('leaves matched brackets (e.g. links) alone when counts balance', () => {
+    const input = 'see [docs](https://example.com) for more';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('fixes the real failing message', () => {
+    const input =
+      'Sure! What do you want to mount, and where should it appear inside the container?\n\n' +
+      '- **Host path** (on your machine): e.g. `~/projects/webapp`\n' +
+      '- **Container path**: e.g. `workspace/webapp`\n' +
+      '- **Read-only or read-write?**';
+    const out = sanitizeTelegramLegacyMarkdown(input);
+    expect(out).not.toContain('**');
+    expect(out).toContain('*Host path*');
+    expect(out).toContain('`~/projects/webapp`');
+    expect((out.match(/\*/g) ?? []).length % 2).toBe(0);
+  });
+
+  it('is a no-op on empty string', () => {
+    expect(sanitizeTelegramLegacyMarkdown('')).toBe('');
+  });
+
+  it('replaces dash list bullets with • so the adapter does not re-emit `*` markers', () => {
+    expect(sanitizeTelegramLegacyMarkdown('- one\n- two')).toBe('• one\n• two');
+  });
+
+  it('preserves indented list structure', () => {
+    expect(sanitizeTelegramLegacyMarkdown('  - nested')).toBe('  • nested');
+  });
+
+  it('flattens Markdown horizontal rules (---, ***, ___)', () => {
+    const input = 'before\n---\n***\n___\nafter';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe('before\n⎯⎯⎯\n⎯⎯⎯\n⎯⎯⎯\nafter');
+  });
+
+  it('leaves horizontal rules inside code blocks alone', () => {
+    const input = '```\n---\n```';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+});

package/src/channels/telegram-markdown-sanitize.ts

@@ -0,0 +1,55 @@
+/**
+ * Sanitize outbound text for Telegram's legacy `Markdown` parse mode.
+ *
+ * WORKAROUND: The @chat-adapter/telegram adapter hardcodes parse_mode=Markdown
+ * (legacy) but its converter emits CommonMark. Messages with `**bold**`, odd
+ * delimiter counts, or malformed links are rejected by Telegram and dropped
+ * after retries. Remove this once upstream ships real mode-aware conversion
+ * (vercel/chat PR #367 adds the knob; a follow-up is needed for the converter).
+ */
+
+const CODE_PATTERN = /```[\s\S]*?```|`[^`\n]*`/g;
+const PLACEHOLDER_PREFIX = '\x00CODE';
+const PLACEHOLDER_SUFFIX = '\x00';
+
+export function sanitizeTelegramLegacyMarkdown(input: string): string {
+  if (!input) return input;
+
+  const codeSegments: string[] = [];
+  let text = input.replace(CODE_PATTERN, (m) => {
+    codeSegments.push(m);
+    return `${PLACEHOLDER_PREFIX}${codeSegments.length - 1}${PLACEHOLDER_SUFFIX}`;
+  });
+
+  // The adapter re-parses and re-stringifies markdown before sending, which
+  // rewrites `- item` list bullets into `* item` — injecting unbalanced
+  // asterisks that Telegram's legacy Markdown parser then rejects. Replace
+  // list bullets with a plain Unicode bullet so the adapter treats the line
+  // as prose.
+  text = text.replace(/^(\s*)[-+]\s+/gm, '$1• ');
+
+  // Flatten Markdown horizontal rules (bare --- / *** / ___ lines) to a
+  // plain Unicode divider. The parser doesn't understand HR syntax and the
+  // `*` / `_` characters would otherwise unbalance the delimiter counts below.
+  text = text.replace(/^[ \t]*[-_*]{3,}[ \t]*$/gm, '⎯⎯⎯');
+
+  text = text.replace(/\*\*([^*\n]+?)\*\*/g, '*$1*');
+  text = text.replace(/__([^_\n]+?)__/g, '_$1_');
+
+  const starCount = (text.match(/\*/g) ?? []).length;
+  const underCount = (text.match(/_/g) ?? []).length;
+  if (starCount % 2 !== 0 || underCount % 2 !== 0) {
+    text = text.replace(/[*_]/g, '');
+  }
+
+  const openBrackets = (text.match(/\[/g) ?? []).length;
+  const closeBrackets = (text.match(/\]/g) ?? []).length;
+  if (openBrackets !== closeBrackets) {
+    text = text.replace(/[[\]]/g, '');
+  }
+
+  return text.replace(
+    new RegExp(`${PLACEHOLDER_PREFIX}(\\d+)${PLACEHOLDER_SUFFIX}`, 'g'),
+    (_, i) => codeSegments[Number(i)],
+  );
+}