@openparachute/agent 0.1.0

package/src/startup-bootstrap.ts

@@ -0,0 +1,207 @@
+/**
+ * Startup-time migrations that depend on runtime state — specifically, the
+ * bot ids resolved at adapter init time. SQL migrations run before adapters
+ * exist, so anything that needs `adapter.botId` (or the operator's `.env`
+ * values) lives here instead of in `src/db/migrations/`.
+ *
+ * Two responsibilities, both idempotent:
+ *
+ *   1. **Token bootstrap** — copy each active adapter's bot token from `.env`
+ *      into the encrypted secrets table, keyed by `<channel>:<botId>`. PR A
+ *      doesn't yet read these tokens back from secrets at adapter spawn; the
+ *      copy exists so PR B's dynamic per-bot polling has a populated table
+ *      to draw from. Re-running the bootstrap with the same value is a no-op.
+ *
+ *   2. **messaging_groups v1→v2 platform_id backfill** — every existing row
+ *      keyed by the v1 form `<channel>:<native>` is rewritten to the v2 form
+ *      `<channel>:<botId>:<native>` so the router's `getMessagingGroupByPlatform`
+ *      lookup matches what the chat-sdk-bridge now emits on inbound. Other
+ *      tables (pending_questions, dropped_messages, pending_approvals, the
+ *      session DBs' messages_in/destinations) are intentionally NOT
+ *      backfilled — consumers compare those like-with-like inside one event
+ *      lifecycle, so a v1 snapshot taken before the upgrade still resolves
+ *      against itself; new rows go in v2-shaped from the moment the bridge
+ *      starts emitting v2 ids.
+ *
+ * Idempotency strategy: detect already-v2 rows by checking whether their
+ * second segment matches *any* known bot id for the channel — the union of
+ * active adapters + every botId persisted under `CHANNEL_BOT_TOKEN:<channel>:`
+ * in the secrets table. Comparing against only the iteration's adapter
+ * misclassifies rows already-v2 for a *secondary* bot as v1 and re-prefixes
+ * them, producing a 4-segment garbage id; consulting secrets too means even
+ * pre-spawn secondary bots (Proposal A defers adapter spawn until wire) are
+ * recognized.
+ */
+import { getDb } from './db/connection.js';
+import { readEnvFile } from './env.js';
+import { log } from './log.js';
+import { encodePlatformId } from './platform-id.js';
+import { getActiveAdapters } from './channels/channel-registry.js';
+import { getSecret, listSecrets, putSecret } from './secrets/index.js';
+
+/** `.env` var name carrying each channel's bot token. Empty for channels
+ *  paraclaw doesn't manage credentials for in `.env` (CLI, native channels). */
+const TOKEN_ENV_FOR_CHANNEL: Record<string, string | undefined> = {
+  telegram: 'TELEGRAM_BOT_TOKEN',
+  discord: 'DISCORD_BOT_TOKEN',
+};
+
+export function channelTokenSecretName(channelType: string, botId: string): string {
+  return `CHANNEL_BOT_TOKEN:${channelType}:${botId}`;
+}
+
+/**
+ * Copy each active adapter's `.env`-sourced bot token into the secrets
+ * table under `CHANNEL_BOT_TOKEN:<channel>:<botId>`. Skips channels with
+ * no `.env` mapping or no resolved botId.
+ */
+export function bootstrapChannelTokensToSecrets(): void {
+  const envVars = Object.values(TOKEN_ENV_FOR_CHANNEL).filter((v): v is string => typeof v === 'string');
+  const env = readEnvFile(envVars);
+  for (const adapter of getActiveAdapters()) {
+    if (!adapter.botId) continue;
+    const envVar = TOKEN_ENV_FOR_CHANNEL[adapter.channelType];
+    if (!envVar) continue;
+    const value = env[envVar];
+    if (!value) continue;
+    const name = channelTokenSecretName(adapter.channelType, adapter.botId);
+    const existing = getSecret(name);
+    if (existing === value) continue;
+    putSecret(name, value, { kind: 'channel-token', agent_group_id: null });
+    if (existing === undefined) {
+      log.info('Bootstrapped channel bot token to secrets', {
+        channelType: adapter.channelType,
+        botId: adapter.botId,
+      });
+    } else {
+      // `.env` value diverged from what we previously stored — operator
+      // rotated the token. Single line so token-rotation events show up
+      // in `logs/parachute-agent.log` without needing a separate
+      // observability surface.
+      log.info('Channel bot token rotated', {
+        channelType: adapter.channelType,
+        botId: adapter.botId,
+      });
+    }
+  }
+}
+
+interface MessagingGroupRow {
+  id: string;
+  channel_type: string;
+  platform_id: string;
+}
+
+/**
+ * True if the platform_id's bot segment matches *any* known bot id for this
+ * channel — not just the active adapter's. The set must be the union of
+ * every botId the install has ever registered (active adapters + persisted
+ * `CHANNEL_BOT_TOKEN:<channel>:<botId>` secrets), or rows already-v2 for a
+ * secondary bot get re-prefixed under the iteration's primary botId and end
+ * up with a 4-segment platform_id like `telegram:primary:secondary:chat`.
+ *
+ * Collision case: if a v1 row's first native segment happens to equal one
+ * of the known bot ids (a Telegram chat_id matching a bot's own user_id, or
+ * a Discord guild id matching an application id), it would be misclassified
+ * as already-v2 and skipped. Vanishingly unlikely given how those id spaces
+ * are allocated — flagged here so a future operator hitting the case knows
+ * where to look.
+ */
+function isAlreadyV2(channelType: string, platformId: string, knownBotIds: ReadonlySet<string>): boolean {
+  const prefix = `${channelType}:`;
+  if (!platformId.startsWith(prefix)) return false;
+  const after = platformId.slice(prefix.length);
+  const colon = after.indexOf(':');
+  const slot1 = colon === -1 ? after : after.slice(0, colon);
+  return knownBotIds.has(slot1);
+}
+
+/**
+ * Union of every known bot id per channel: the live adapters + every botId
+ * that appears in a `CHANNEL_BOT_TOKEN:<channel>:<botId>` secret name. We
+ * consult secrets because at boot only the `.env` primary is yet active;
+ * secondary bots persisted via `/register-bot` haven't been adapter-spawned
+ * yet (Proposal A defers spawn until `/wire-channel`), but their tokens are
+ * already in the secrets table — and rows pointing at them are already v2.
+ */
+function knownBotIdsPerChannel(): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  const add = (channel: string, botId: string) => {
+    let set = out.get(channel);
+    if (!set) {
+      set = new Set();
+      out.set(channel, set);
+    }
+    set.add(botId);
+  };
+  for (const a of getActiveAdapters()) {
+    if (a.botId) add(a.channelType, a.botId);
+  }
+  for (const s of listSecrets(null)) {
+    if (s.kind !== 'channel-token') continue;
+    const parts = s.name.split(':');
+    if (parts.length < 3 || parts[0] !== 'CHANNEL_BOT_TOKEN') continue;
+    const channel = parts[1];
+    const botId = parts.slice(2).join(':');
+    if (!channel || !botId) continue;
+    add(channel, botId);
+  }
+  return out;
+}
+
+/**
+ * Rewrite v1 platform_ids in `messaging_groups` to v2 for every channel
+ * with an active per-bot adapter. Returns the number of rows upgraded
+ * (used by the bootstrap log line and tests).
+ */
+export function backfillMessagingGroupsToV2(): number {
+  const adapters = getActiveAdapters().filter((a) => a.botId);
+  if (adapters.length === 0) return 0;
+  const knownByChannel = knownBotIdsPerChannel();
+  const select = getDb().prepare<MessagingGroupRow>(
+    `SELECT id, channel_type, platform_id
+       FROM messaging_groups
+      WHERE channel_type = @channel_type`,
+  );
+  const update = getDb().prepare(`UPDATE messaging_groups SET platform_id = @platform_id WHERE id = @id`);
+  let totalUpgraded = 0;
+  for (const adapter of adapters) {
+    const channel = adapter.channelType;
+    const botId = adapter.botId!;
+    const known = knownByChannel.get(channel) ?? new Set([botId]);
+    const rows = select.all({ channel_type: channel });
+    let upgraded = 0;
+    for (const row of rows) {
+      if (isAlreadyV2(channel, row.platform_id, known)) continue;
+      const prefix = `${channel}:`;
+      if (!row.platform_id.startsWith(prefix)) continue;
+      const native = row.platform_id.slice(prefix.length);
+      const v2 = encodePlatformId(channel, botId, native);
+      try {
+        update.run({ id: row.id, platform_id: v2 });
+        upgraded += 1;
+      } catch (err) {
+        log.error('messaging_groups v2 backfill failed (UNIQUE conflict?)', {
+          id: row.id,
+          from: row.platform_id,
+          to: v2,
+          err,
+        });
+      }
+    }
+    if (upgraded > 0) {
+      log.info('messaging_groups backfilled to v2', {
+        channelType: channel,
+        botId,
+        upgraded,
+      });
+      totalUpgraded += upgraded;
+    }
+  }
+  return totalUpgraded;
+}
+
+export function runStartupBootstrap(): void {
+  backfillMessagingGroupsToV2();
+  bootstrapChannelTokensToSecrets();
+}

package/src/state-sqlite.ts

@@ -0,0 +1,182 @@
+/**
+ * Chat SDK StateAdapter backed by SQLite.
+ * Persists subscriptions, locks, KV, and lists across restarts.
+ *
+ * Ported from feat/chat-sdk-integration branch.
+ */
+import crypto from 'crypto';
+
+import type { Database } from './db/connection.js';
+import type { StateAdapter, QueueEntry } from 'chat';
+
+import { getDb } from './db/connection.js';
+
+interface Lock {
+  threadId: string;
+  token: string;
+  expiresAt: number;
+}
+
+export class SqliteStateAdapter implements StateAdapter {
+  private db!: Database;
+
+  async connect(): Promise<void> {
+    this.db = getDb();
+    this.cleanup();
+  }
+
+  async disconnect(): Promise<void> {}
+
+  // --- Key-value ---
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    this.cleanup();
+    const row = this.db.prepare('SELECT value, expires_at FROM chat_sdk_kv WHERE key = ?').get(key) as
+      | { value: string; expires_at: number | null }
+      | undefined;
+    if (!row) return null;
+    if (row.expires_at && row.expires_at < Date.now()) {
+      this.db.prepare('DELETE FROM chat_sdk_kv WHERE key = ?').run(key);
+      return null;
+    }
+    return JSON.parse(row.value) as T;
+  }
+
+  async set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> {
+    const expiresAt = ttlMs ? Date.now() + ttlMs : null;
+    this.db
+      .prepare('INSERT OR REPLACE INTO chat_sdk_kv (key, value, expires_at) VALUES (?, ?, ?)')
+      .run(key, JSON.stringify(value), expiresAt);
+  }
+
+  async setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean> {
+    const existing = this.db.prepare('SELECT expires_at FROM chat_sdk_kv WHERE key = ?').get(key) as
+      | { expires_at: number | null }
+      | undefined;
+    if (existing?.expires_at && existing.expires_at < Date.now()) {
+      this.db.prepare('DELETE FROM chat_sdk_kv WHERE key = ?').run(key);
+    }
+    const expiresAt = ttlMs ? Date.now() + ttlMs : null;
+    const result = this.db
+      .prepare('INSERT OR IGNORE INTO chat_sdk_kv (key, value, expires_at) VALUES (?, ?, ?)')
+      .run(key, JSON.stringify(value), expiresAt);
+    return result.changes > 0;
+  }
+
+  async delete(key: string): Promise<void> {
+    this.db.prepare('DELETE FROM chat_sdk_kv WHERE key = ?').run(key);
+  }
+
+  // --- Subscriptions ---
+
+  async subscribe(threadId: string): Promise<void> {
+    this.db.prepare('INSERT OR REPLACE INTO chat_sdk_subscriptions (thread_id) VALUES (?)').run(threadId);
+  }
+
+  async unsubscribe(threadId: string): Promise<void> {
+    this.db.prepare('DELETE FROM chat_sdk_subscriptions WHERE thread_id = ?').run(threadId);
+  }
+
+  async isSubscribed(threadId: string): Promise<boolean> {
+    const row = this.db.prepare('SELECT 1 FROM chat_sdk_subscriptions WHERE thread_id = ? LIMIT 1').get(threadId);
+    return !!row;
+  }
+
+  // --- Locks ---
+
+  async acquireLock(threadId: string, ttlMs: number): Promise<Lock | null> {
+    const now = Date.now();
+    const token = crypto.randomUUID();
+    const expiresAt = now + ttlMs;
+    this.db.prepare('DELETE FROM chat_sdk_locks WHERE thread_id = ? AND expires_at < ?').run(threadId, now);
+    const result = this.db
+      .prepare('INSERT OR IGNORE INTO chat_sdk_locks (thread_id, token, expires_at) VALUES (?, ?, ?)')
+      .run(threadId, token, expiresAt);
+    if (result.changes === 0) return null;
+    return { threadId, token, expiresAt };
+  }
+
+  async releaseLock(lock: Lock): Promise<void> {
+    this.db.prepare('DELETE FROM chat_sdk_locks WHERE thread_id = ? AND token = ?').run(lock.threadId, lock.token);
+  }
+
+  async extendLock(lock: Lock, ttlMs: number): Promise<boolean> {
+    const newExpiry = Date.now() + ttlMs;
+    const result = this.db
+      .prepare('UPDATE chat_sdk_locks SET expires_at = ? WHERE thread_id = ? AND token = ?')
+      .run(newExpiry, lock.threadId, lock.token);
+    if (result.changes > 0) {
+      lock.expiresAt = newExpiry;
+      return true;
+    }
+    return false;
+  }
+
+  async forceReleaseLock(threadId: string): Promise<void> {
+    this.db.prepare('DELETE FROM chat_sdk_locks WHERE thread_id = ?').run(threadId);
+  }
+
+  // --- Lists ---
+
+  async appendToList(key: string, value: unknown, options?: { maxLength?: number; ttlMs?: number }): Promise<void> {
+    const expiresAt = options?.ttlMs ? Date.now() + options.ttlMs : null;
+    const maxRow = this.db.prepare('SELECT MAX(idx) as maxIdx FROM chat_sdk_lists WHERE key = ?').get(key) as
+      | { maxIdx: number | null }
+      | undefined;
+    const nextIdx = (maxRow?.maxIdx ?? -1) + 1;
+    this.db
+      .prepare('INSERT INTO chat_sdk_lists (key, idx, value, expires_at) VALUES (?, ?, ?, ?)')
+      .run(key, nextIdx, JSON.stringify(value), expiresAt);
+    if (options?.maxLength) {
+      const cutoff = nextIdx - options.maxLength;
+      if (cutoff >= 0) {
+        this.db.prepare('DELETE FROM chat_sdk_lists WHERE key = ? AND idx <= ?').run(key, cutoff);
+      }
+    }
+  }
+
+  async getList<T = unknown>(key: string): Promise<T[]> {
+    const now = Date.now();
+    const rows = this.db
+      .prepare(
+        'SELECT value FROM chat_sdk_lists WHERE key = ? AND (expires_at IS NULL OR expires_at > ?) ORDER BY idx ASC',
+      )
+      .all(key, now) as { value: string }[];
+    return rows.map((r) => JSON.parse(r.value) as T);
+  }
+
+  // --- Queue ---
+
+  async enqueue(threadId: string, entry: QueueEntry, maxSize: number): Promise<number> {
+    const key = `queue:${threadId}`;
+    await this.appendToList(key, entry, { maxLength: maxSize });
+    return await this.queueDepth(threadId);
+  }
+
+  async dequeue(threadId: string): Promise<QueueEntry | null> {
+    const key = `queue:${threadId}`;
+    const row = this.db
+      .prepare('SELECT idx, value FROM chat_sdk_lists WHERE key = ? ORDER BY idx ASC LIMIT 1')
+      .get(key) as { idx: number; value: string } | undefined;
+    if (!row) return null;
+    this.db.prepare('DELETE FROM chat_sdk_lists WHERE key = ? AND idx = ?').run(key, row.idx);
+    return JSON.parse(row.value) as QueueEntry;
+  }
+
+  async queueDepth(threadId: string): Promise<number> {
+    const key = `queue:${threadId}`;
+    const row = this.db.prepare('SELECT COUNT(*) as count FROM chat_sdk_lists WHERE key = ?').get(key) as {
+      count: number;
+    };
+    return row.count;
+  }
+
+  // --- Cleanup ---
+
+  private cleanup(): void {
+    const now = Date.now();
+    this.db.prepare('DELETE FROM chat_sdk_kv WHERE expires_at IS NOT NULL AND expires_at < ?').run(now);
+    this.db.prepare('DELETE FROM chat_sdk_locks WHERE expires_at < ?').run(now);
+    this.db.prepare('DELETE FROM chat_sdk_lists WHERE expires_at IS NOT NULL AND expires_at < ?').run(now);
+  }
+}

package/src/timezone.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+
+import { formatLocalTime, isValidTimezone, resolveTimezone } from './timezone.js';
+
+// --- formatLocalTime ---
+
+describe('formatLocalTime', () => {
+  it('converts UTC to local time display', () => {
+    // 2026-02-04T18:30:00Z in America/New_York (EST, UTC-5) = 1:30 PM
+    const result = formatLocalTime('2026-02-04T18:30:00.000Z', 'America/New_York');
+    expect(result).toContain('1:30');
+    expect(result).toContain('PM');
+    expect(result).toContain('Feb');
+    expect(result).toContain('2026');
+  });
+
+  it('handles different timezones', () => {
+    // Same UTC time should produce different local times
+    const utc = '2026-06-15T12:00:00.000Z';
+    const ny = formatLocalTime(utc, 'America/New_York');
+    const tokyo = formatLocalTime(utc, 'Asia/Tokyo');
+    // NY is UTC-4 in summer (EDT), Tokyo is UTC+9
+    expect(ny).toContain('8:00');
+    expect(tokyo).toContain('9:00');
+  });
+
+  it('does not throw on invalid timezone, falls back to UTC', () => {
+    expect(() => formatLocalTime('2026-01-01T00:00:00.000Z', 'IST-2')).not.toThrow();
+    const result = formatLocalTime('2026-01-01T12:00:00.000Z', 'IST-2');
+    // Should format as UTC (noon UTC = 12:00 PM)
+    expect(result).toContain('12:00');
+    expect(result).toContain('PM');
+  });
+});
+
+describe('isValidTimezone', () => {
+  it('accepts valid IANA identifiers', () => {
+    expect(isValidTimezone('America/New_York')).toBe(true);
+    expect(isValidTimezone('UTC')).toBe(true);
+    expect(isValidTimezone('Asia/Tokyo')).toBe(true);
+    expect(isValidTimezone('Asia/Jerusalem')).toBe(true);
+  });
+
+  it('rejects invalid timezone strings', () => {
+    expect(isValidTimezone('IST-2')).toBe(false);
+    expect(isValidTimezone('XYZ+3')).toBe(false);
+  });
+
+  it('rejects empty and garbage strings', () => {
+    expect(isValidTimezone('')).toBe(false);
+    expect(isValidTimezone('NotATimezone')).toBe(false);
+  });
+});
+
+describe('resolveTimezone', () => {
+  it('returns the timezone if valid', () => {
+    expect(resolveTimezone('America/New_York')).toBe('America/New_York');
+  });
+
+  it('falls back to UTC for invalid timezone', () => {
+    expect(resolveTimezone('IST-2')).toBe('UTC');
+    expect(resolveTimezone('')).toBe('UTC');
+  });
+});

package/src/timezone.ts

@@ -0,0 +1,37 @@
+/**
+ * Check whether a timezone string is a valid IANA identifier
+ * that Intl.DateTimeFormat can use.
+ */
+export function isValidTimezone(tz: string): boolean {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the given timezone if valid IANA, otherwise fall back to UTC.
+ */
+export function resolveTimezone(tz: string): string {
+  return isValidTimezone(tz) ? tz : 'UTC';
+}
+
+/**
+ * Convert a UTC ISO timestamp to a localized display string.
+ * Uses the Intl API (no external dependencies).
+ * Falls back to UTC if the timezone is invalid.
+ */
+export function formatLocalTime(utcIso: string, timezone: string): string {
+  const date = new Date(utcIso);
+  return date.toLocaleString('en-US', {
+    timeZone: resolveTimezone(timezone),
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}