@openparachute/agent 0.1.0

package/scripts/test-v2-host.ts

@@ -0,0 +1,184 @@
+/**
+ * Real end-to-end test of v2: host router → Docker container → agent-runner → delivery.
+ *
+ * 1. Init central DB with agent group + messaging group + wiring
+ * 2. Route an inbound message (creates session, writes inbound.db, spawns container)
+ * 3. Container runs v2 agent-runner, polls inbound.db, queries Claude, writes outbound.db
+ * 4. Poll outbound.db for messages_out response
+ *
+ * Usage: pnpm exec tsx scripts/test-v2-host.ts
+ */
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+
+const TEST_DIR = '/tmp/paraclaw-v2-e2e';
+if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+fs.mkdirSync(TEST_DIR, { recursive: true });
+
+// --- Step 1: Init central DB ---
+console.log('\n=== Step 1: Init central DB ===');
+
+import { initDb } from '../src/db/connection.js';
+import { runMigrations } from '../src/db/migrations/index.js';
+import { createAgentGroup } from '../src/db/agent-groups.js';
+import { createMessagingGroup, createMessagingGroupAgent } from '../src/db/messaging-groups.js';
+
+const centralDb = initDb(path.join(TEST_DIR, 'v2.db'));
+runMigrations(centralDb);
+
+// Create groups dir for agent folder mount
+const groupsDir = path.resolve(process.cwd(), 'groups');
+const testGroupDir = path.join(groupsDir, 'test-agent-e2e');
+fs.mkdirSync(testGroupDir, { recursive: true });
+fs.writeFileSync(path.join(testGroupDir, 'CLAUDE.md'), '# Test Agent\nYou are a test agent. Be brief.\n');
+
+createAgentGroup({
+  id: 'ag-e2e',
+  name: 'E2E Test Agent',
+  folder: 'test-agent-e2e',
+  agent_provider: 'claude',
+  created_at: new Date().toISOString(),
+});
+
+createMessagingGroup({
+  id: 'mg-e2e',
+  channel_type: 'test',
+  platform_id: 'e2e-channel',
+  name: 'E2E Test Channel',
+  is_group: 0,
+  unknown_sender_policy: 'public',
+  created_at: new Date().toISOString(),
+});
+
+createMessagingGroupAgent({
+  id: 'mga-e2e',
+  messaging_group_id: 'mg-e2e',
+  agent_group_id: 'ag-e2e',
+  engage_mode: 'pattern',
+  engage_pattern: '.',
+  sender_scope: 'all',
+  ignored_message_policy: 'drop',
+  session_mode: 'shared',
+  priority: 0,
+  created_at: new Date().toISOString(),
+});
+
+console.log('✓ Central DB initialized');
+
+// --- Step 2: Route inbound message (spawns container) ---
+console.log('\n=== Step 2: Route inbound message ===');
+
+import { routeInbound } from '../src/router.js';
+import { findSession } from '../src/db/sessions.js';
+import { inboundDbPath, outboundDbPath } from '../src/session-manager.js';
+
+await routeInbound({
+  channelType: 'test',
+  platformId: 'e2e-channel',
+  threadId: null,
+  message: {
+    id: 'msg-e2e-1',
+    kind: 'chat',
+    content: JSON.stringify({
+      sender: 'Gavriel',
+      text: 'Say "E2E works!" and nothing else. Do not use any tools.',
+    }),
+    timestamp: new Date().toISOString(),
+  },
+});
+
+const session = findSession('mg-e2e', null);
+if (!session) {
+  console.log('✗ No session created!');
+  process.exit(1);
+}
+console.log(`✓ Session: ${session.id}`);
+console.log(`✓ Container status: ${session.container_status}`);
+
+const inDbPath = inboundDbPath('ag-e2e', session.id);
+const outDbPath = outboundDbPath('ag-e2e', session.id);
+console.log(`✓ Inbound DB: ${inDbPath}`);
+console.log(`✓ Outbound DB: ${outDbPath}`);
+
+// --- Step 3: Wait for response ---
+console.log('\n=== Step 3: Waiting for Claude response... ===');
+
+const startTime = Date.now();
+const TIMEOUT_MS = 120_000;
+
+const checkForResponse = (): boolean => {
+  try {
+    const db = new Database(outDbPath, { readonly: true });
+    const out = db.prepare('SELECT * FROM messages_out').all() as Array<Record<string, unknown>>;
+    db.close();
+    return out.length > 0;
+  } catch {
+    return false;
+  }
+};
+
+await new Promise<void>((resolve) => {
+  const poll = () => {
+    if (checkForResponse()) {
+      resolve();
+      return;
+    }
+    if (Date.now() - startTime > TIMEOUT_MS) {
+      console.log(`\n✗ Timed out after ${TIMEOUT_MS / 1000}s`);
+      printState();
+      process.exit(1);
+    }
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    if (elapsed > 0 && elapsed % 10 === 0) {
+      process.stdout.write(`  ${elapsed}s...`);
+    }
+    setTimeout(poll, 1000);
+  };
+  poll();
+});
+
+// --- Step 4: Print results ---
+console.log('\n\n=== Results ===');
+printState();
+
+// Clean up test group dir
+fs.rmSync(testGroupDir, { recursive: true, force: true });
+
+process.exit(0);
+
+function printState() {
+  try {
+    const inDb = new Database(inDbPath, { readonly: true });
+    const inRows = inDb.prepare('SELECT * FROM messages_in').all() as Array<Record<string, unknown>>;
+    inDb.close();
+
+    console.log('\nmessages_in (inbound.db):');
+    for (const r of inRows) {
+      console.log(`  [${r.id}] status=${r.status} kind=${r.kind}`);
+    }
+  } catch (err) {
+    console.log(`  (could not read inbound DB: ${err})`);
+  }
+
+  try {
+    const outDb = new Database(outDbPath, { readonly: true });
+    const outRows = outDb.prepare('SELECT * FROM messages_out').all() as Array<Record<string, unknown>>;
+    const ackRows = outDb.prepare('SELECT * FROM processing_ack').all() as Array<Record<string, unknown>>;
+    outDb.close();
+
+    console.log('\nmessages_out (outbound.db):');
+    for (const r of outRows) {
+      const content = JSON.parse(r.content as string);
+      console.log(`  [${r.id}] kind=${r.kind}`);
+      console.log(`  → ${content.text}`);
+    }
+
+    console.log('\nprocessing_ack (outbound.db):');
+    for (const r of ackRows) {
+      console.log(`  [${r.message_id}] status=${r.status} changed=${r.status_changed}`);
+    }
+  } catch (err) {
+    console.log(`  (could not read outbound DB: ${err})`);
+  }
+}

package/src/channels/adapter.ts

@@ -0,0 +1,214 @@
+/**
+ * v2 Channel Adapter interface.
+ *
+ * Channel adapters bridge Paraclaw with messaging platforms (Discord, Slack, etc.).
+ * Two patterns: native adapters (implement directly) or Chat SDK bridge (wrap a Chat SDK adapter).
+ */
+
+/** Passed to the adapter at setup time. */
+export interface ChannelSetup {
+  /** Called when an inbound message arrives from the platform. */
+  onInbound(platformId: string, threadId: string | null, message: InboundMessage): void | Promise<void>;
+
+  /**
+   * Called by admin-transport adapters (CLI) that want to route a message to
+   * an arbitrary channel/platform and optionally redirect replies elsewhere.
+   * Regular chat adapters should use `onInbound`; `onInboundEvent` skips the
+   * adapter-channel-type injection so the caller can target any wired mg.
+   */
+  onInboundEvent(event: InboundEvent): void | Promise<void>;
+
+  /** Called when the adapter discovers metadata about a conversation. */
+  onMetadata(platformId: string, name?: string, isGroup?: boolean): void;
+
+  /** Called when a user clicks a button/action in a card (e.g., ask_user_question response). */
+  onAction(questionId: string, selectedOption: string, userId: string): void;
+}
+
+/** Delivery address used for reply-to overrides and (normally) the inbound's own origin. */
+export interface DeliveryAddress {
+  channelType: string;
+  platformId: string;
+  threadId: string | null;
+}
+
+/**
+ * Full inbound event handed to the router.
+ *
+ * `channelType` + `platformId` + `threadId` identify which messaging group /
+ * session receives the message. `replyTo`, when set, overrides where the
+ * agent's reply is delivered — used by the CLI admin transport when the
+ * operator wants a message routed to one channel but replies echoed back to
+ * their terminal. Agents cannot set `replyTo`; it is a router-layer concept
+ * set only by external adapters carrying operator intent.
+ */
+export interface InboundEvent {
+  channelType: string;
+  platformId: string;
+  threadId: string | null;
+  message: {
+    id: string;
+    kind: 'chat' | 'chat-sdk';
+    content: string; // JSON blob
+    timestamp: string;
+    /**
+     * Platform-confirmed bot-mention signal forwarded from the adapter.
+     * See InboundMessage.isMention for the full explanation.
+     */
+    isMention?: boolean;
+    /** True when the source is a group/channel thread, false for DMs. */
+    isGroup?: boolean;
+  };
+  replyTo?: DeliveryAddress;
+}
+
+/** Inbound message from adapter to host. */
+export interface InboundMessage {
+  id: string;
+  kind: 'chat' | 'chat-sdk';
+  content: unknown; // JS object — host will JSON.stringify before writing to session DB
+  timestamp: string;
+  /**
+   * Platform-confirmed signal that this message is a mention of the bot.
+   *
+   * Set by adapters that know the platform's own mention semantics — e.g.
+   * the Chat SDK bridge sets it true from `onNewMention` / `onDirectMessage`
+   * and forwards `message.isMention` from `onSubscribedMessage`. Use this
+   * in the router instead of agent-name regex matching, which breaks on
+   * platforms where the mention text is the bot's platform username (e.g.
+   * Telegram's `@paraclaw_refactr_bot`) rather than the agent_group
+   * display name (e.g. `@Andy`).
+   *
+   * Adapters that don't set it (native / legacy) leave it undefined — the
+   * router falls back to text-match against agent_group_name.
+   */
+  isMention?: boolean;
+  /** True when the source is a group/channel thread, false for DMs. */
+  isGroup?: boolean;
+}
+
+/** A file attachment to deliver alongside a message. */
+export interface OutboundFile {
+  filename: string;
+  data: Buffer;
+}
+
+/** Outbound message from host to adapter. */
+export interface OutboundMessage {
+  kind: string;
+  content: unknown; // parsed JSON from messages_out
+  files?: OutboundFile[]; // file attachments from the session outbox
+}
+
+/** Discovered conversation info (from syncConversations). */
+export interface ConversationInfo {
+  platformId: string;
+  name: string;
+  isGroup: boolean;
+}
+
+/** The v2 channel adapter contract. */
+export interface ChannelAdapter {
+  name: string;
+  channelType: string;
+
+  /**
+   * Stable per-bot identity used as the second segment of v2 platform_ids
+   * (`<channel>:<botId>:<native>`). Null/undefined for adapters that have
+   * no bot dimension at all (CLI admin transport). Resolved at adapter
+   * factory time — Telegram via `getMe.id`, Discord via
+   * `DISCORD_APPLICATION_ID`. Used by the registry to look up the right
+   * adapter when delivering a v2 platform_id back out.
+   */
+  botId?: string | null;
+
+  /**
+   * Whether this adapter models conversations as threads.
+   *
+   * true  — adapter's platform uses threads as the primary conversation unit
+   *         (Discord, Slack, Linear, GitHub). One thread = one session; the
+   *         agent replies into the originating thread.
+   * false — adapter's platform treats the channel itself as the conversation
+   *         (Telegram, WhatsApp, iMessage). Thread ids are stripped at the
+   *         router; agent replies go to the channel.
+   */
+  supportsThreads: boolean;
+
+  // Lifecycle
+  setup(config: ChannelSetup): Promise<void>;
+  teardown(): Promise<void>;
+  isConnected(): boolean;
+
+  // Outbound delivery — returns the platform message ID if available
+  deliver(platformId: string, threadId: string | null, message: OutboundMessage): Promise<string | undefined>;
+
+  // Optional
+  setTyping?(platformId: string, threadId: string | null): Promise<void>;
+  syncConversations?(): Promise<ConversationInfo[]>;
+
+  /**
+   * Subscribe the bot to a thread so follow-up messages route via the
+   * platform's "subscribed message" path (onSubscribedMessage in Chat SDK).
+   * Called by the router when a mention-sticky wiring first engages in a
+   * thread. Idempotent: calling twice on the same thread is a no-op.
+   *
+   * Platforms without a subscription concept can omit this; the router
+   * treats absence as a no-op.
+   */
+  subscribe?(platformId: string, threadId: string): Promise<void>;
+
+  /**
+   * Open (or fetch) a DM with this user, returning the platform_id of the
+   * resulting DM channel. Called by the host on demand to initiate cold
+   * DMs — approvals, pairing handshakes, host-initiated notifications — to
+   * users who may never have messaged the bot themselves.
+   *
+   * Omit this method on channels where the user handle IS already the DM
+   * chat id (Telegram, WhatsApp, iMessage, email, Matrix). Callers will
+   * fall through to using the handle directly.
+   *
+   * For channels that distinguish user id from DM channel id (Discord,
+   * Slack, Teams, Webex, gChat): implement by delegating to Chat SDK's
+   * chat.openDM, which hits the platform's idempotent open-DM endpoint.
+   * Returning the same platform_id on repeated calls is expected.
+   */
+  openDM?(userHandle: string): Promise<string>;
+}
+
+/** Factory function that creates a channel adapter (returns null if credentials missing). */
+export type ChannelAdapterFactory = () => ChannelAdapter | null | Promise<ChannelAdapter | null>;
+
+/**
+ * Build an adapter from a stored secret. Channel modules implement this so
+ * the registry's secrets-backed startup scan and the dynamic register-bot
+ * endpoint can spawn additional bot adapters beyond the `.env`-defined
+ * primary, without channel-registry needing to know per-channel internals.
+ *
+ * Receives the full secret name (e.g. `CHANNEL_BOT_TOKEN:discord:9128…`)
+ * and its plaintext value (the bot token). Adapters that need more than
+ * just a token (Discord needs `applicationId`) parse it out of the name's
+ * trailing segment, which by convention is the bot's identity.
+ *
+ * Returns the adapter ready for `setup()`; the caller wires up host
+ * callbacks. Returns null if the secret can't produce a viable adapter
+ * (e.g. token rejected by the platform); callers log + skip.
+ */
+export type ChannelSpawnFromSecret = (secretName: string, secretValue: string) => Promise<ChannelAdapter | null>;
+
+/** Registration entry for a channel adapter. */
+export interface ChannelRegistration {
+  factory: ChannelAdapterFactory;
+  /**
+   * Optional. Channels that support multi-bot operation expose this so the
+   * registry can spawn additional bots from `CHANNEL_BOT_TOKEN:<channel>:*`
+   * secrets at boot time and on-demand via the register-bot HTTP endpoint.
+   *
+   * Channels without it support exactly one bot per install (the
+   * `.env`-defined primary).
+   */
+  spawnFromSecret?: ChannelSpawnFromSecret;
+  containerConfig?: {
+    mounts?: Array<{ hostPath: string; containerPath: string; readonly: boolean }>;
+    env?: Record<string, string>;
+  };
+}

package/src/channels/ask-question.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared ask_question payload schema + normalization.
+ *
+ * Producers (host-side approvals, container-side ask_user_question MCP tool)
+ * emit an `ask_question` payload. Options may be bare strings for ergonomics,
+ * but are normalized here into a consistent shape before delivery, persistence,
+ * and rendering.
+ */
+
+export interface OptionInput {
+  label: string;
+  selectedLabel?: string;
+  value?: string;
+}
+
+export type RawOption = string | OptionInput;
+
+export interface NormalizedOption {
+  label: string;
+  selectedLabel: string;
+  value: string;
+}
+
+export function normalizeOption(raw: RawOption): NormalizedOption {
+  if (typeof raw === 'string') {
+    return { label: raw, selectedLabel: raw, value: raw };
+  }
+  const label = raw.label;
+  return {
+    label,
+    selectedLabel: raw.selectedLabel ?? label,
+    value: raw.value ?? label,
+  };
+}
+
+export function normalizeOptions(raws: RawOption[]): NormalizedOption[] {
+  return raws.map(normalizeOption);
+}
+
+export interface AskQuestionPayload {
+  type: 'ask_question';
+  questionId: string;
+  title: string;
+  question: string;
+  options: NormalizedOption[];
+}