@openparachute/agent 0.1.0

package/src/modules/agent-to-agent/db/agent-destinations.ts

@@ -0,0 +1,135 @@
+/**
+ * Per-agent destination map + ACL.
+ *
+ * Each row means: agent `agent_group_id` is allowed to send messages to
+ * target (`target_type`, `target_id`), and refers to it locally as `local_name`.
+ *
+ * Names are local to each source agent — they exist only inside that agent's
+ * namespace. The host uses this table both for routing (resolve name → ID)
+ * and for permission checks (row exists ⇒ authorized).
+ */
+/**
+ * ⚠️  DESTINATION PROJECTION INVARIANT — READ BEFORE ADDING NEW CALL SITES.
+ *
+ * `agent_destinations` in the central DB is the source of truth, but the
+ * agent-runner container reads its destinations from a per-session
+ * projection in `inbound.db`. That projection is written by
+ * `writeDestinations(agentGroupId, sessionId)` in session-manager.ts.
+ *
+ * `spawnContainer` calls `writeDestinations` on every container wake, so a
+ * fresh container always sees the latest destinations. BUT: a container
+ * that is ALREADY running when you mutate the central table will keep
+ * serving the stale projection until its next wake — the central write
+ * does not propagate automatically.
+ *
+ * **Therefore: every time you call `createDestination` / `deleteDestination` /
+ * `deleteAllDestinationsTouching` from code that runs while an agent's
+ * container may be alive, you MUST also call `writeDestinations(agentGroupId,
+ * sessionId)` for each affected session.** Forgetting this manifests as
+ * "dropped: unknown destination" errors at send_message time.
+ *
+ * Affected call sites today (keep this list honest if you add more):
+ *   - src/delivery.ts::handleSystemAction case 'create_agent'
+ *   - src/db/messaging-groups.ts::createMessagingGroupAgent
+ */
+import type { AgentDestination } from '../../../types.js';
+import { getDb } from '../../../db/connection.js';
+
+/**
+ * ⚠️  Caller responsibility: after this returns, call
+ * `writeDestinations(row.agent_group_id, <sessionId>)` for each active
+ * session of that agent group so the change propagates to the running
+ * container's inbound.db. See the top-of-file invariant.
+ */
+export function createDestination(row: AgentDestination): void {
+  getDb()
+    .prepare(
+      `INSERT INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+       VALUES (@agent_group_id, @local_name, @target_type, @target_id, @created_at)`,
+    )
+    .run(row);
+}
+
+export function getDestinations(agentGroupId: string): AgentDestination[] {
+  return getDb()
+    .prepare('SELECT * FROM agent_destinations WHERE agent_group_id = ?')
+    .all(agentGroupId) as AgentDestination[];
+}
+
+export function getDestinationByName(agentGroupId: string, localName: string): AgentDestination | undefined {
+  return getDb()
+    .prepare('SELECT * FROM agent_destinations WHERE agent_group_id = ? AND local_name = ?')
+    .get(agentGroupId, localName) as AgentDestination | undefined;
+}
+
+/** Reverse lookup: what does this agent call the given target? */
+export function getDestinationByTarget(
+  agentGroupId: string,
+  targetType: 'channel' | 'agent',
+  targetId: string,
+): AgentDestination | undefined {
+  return getDb()
+    .prepare('SELECT * FROM agent_destinations WHERE agent_group_id = ? AND target_type = ? AND target_id = ?')
+    .get(agentGroupId, targetType, targetId) as AgentDestination | undefined;
+}
+
+/** Permission check: can this agent send to this target? */
+export function hasDestination(agentGroupId: string, targetType: 'channel' | 'agent', targetId: string): boolean {
+  const row = getDb()
+    .prepare('SELECT 1 FROM agent_destinations WHERE agent_group_id = ? AND target_type = ? AND target_id = ? LIMIT 1')
+    .get(agentGroupId, targetType, targetId);
+  return !!row;
+}
+
+/**
+ * ⚠️  Caller responsibility: after this returns, call
+ * `writeDestinations(agentGroupId, <sessionId>)` for each active session
+ * so the deletion propagates to the running container's inbound.db.
+ */
+export function deleteDestination(agentGroupId: string, localName: string): void {
+  getDb()
+    .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ? AND local_name = ?')
+    .run(agentGroupId, localName);
+}
+
+/**
+ * Delete every destination row where this agent group is either the owner
+ * or the target. Used when tearing down a dev agent after a swap request
+ * completes/rolls-back — drops the bidirectional destinations in one call.
+ *
+ * ⚠️  Caller responsibility: not only does `agentGroupId`'s own session
+ * projection need a refresh, but ALSO every OTHER agent group that had
+ * `agentGroupId` as a destination target. Use `getDestinationReferencers`
+ * below to find them BEFORE calling this (the rows are gone afterwards).
+ */
+export function deleteAllDestinationsTouching(agentGroupId: string): void {
+  getDb()
+    .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ? OR (target_type = ? AND target_id = ?)')
+    .run(agentGroupId, 'agent', agentGroupId);
+}
+
+/**
+ * Return the list of agent_group_ids that currently have a destination
+ * row pointing at `targetAgentGroupId`. Call this BEFORE
+ * `deleteAllDestinationsTouching` if you need to know whose session
+ * projections to refresh after the delete — the rows are gone once the
+ * delete runs.
+ */
+export function getDestinationReferencers(targetAgentGroupId: string): string[] {
+  const rows = getDb()
+    .prepare(
+      "SELECT DISTINCT agent_group_id FROM agent_destinations WHERE target_type = 'agent' AND target_id = ? AND agent_group_id != ?",
+    )
+    .all(targetAgentGroupId, targetAgentGroupId) as Array<{ agent_group_id: string }>;
+  return rows.map((r) => r.agent_group_id);
+}
+
+/** Normalize a human-readable name into a lowercase, dash-separated identifier. */
+export function normalizeName(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'unnamed'
+  );
+}

package/src/modules/agent-to-agent/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent-to-agent module — inter-agent messaging and on-demand agent creation.
+ *
+ * Registers one delivery action (`create_agent`). The sibling `channel_type === 'agent'`
+ * routing path is NOT a system action — core `delivery.ts` dispatches into
+ * `./agent-route.js` via a dynamic import when it sees `msg.channel_type === 'agent'`.
+ *
+ * Host integration points:
+ *   - `src/container-runner.ts::spawnContainer` dynamically imports
+ *     `./write-destinations.js` on every wake (guarded by `hasTable('agent_destinations')`).
+ *   - `src/delivery.ts::deliverMessage` dynamically imports `./agent-route.js`
+ *     when `msg.channel_type === 'agent'`.
+ *
+ * Without this module: `agent_destinations` table absent ⇒ container-runner
+ * skips destination projection, ACL check in delivery skips, `create_agent`
+ * system action logs "Unknown system action", `channel_type='agent'` messages
+ * throw because the module isn't installed.
+ */
+import { registerDeliveryAction } from '../../delivery.js';
+import { handleCreateAgent } from './create-agent.js';
+
+registerDeliveryAction('create_agent', handleCreateAgent);

package/src/modules/agent-to-agent/write-destinations.ts

@@ -0,0 +1,59 @@
+/**
+ * Project the agent's central `agent_destinations` rows into its per-session
+ * `inbound.db` so the running container can resolve names locally. Called on
+ * every container wake and after admin-time destination edits (e.g. create_agent).
+ *
+ * Core container-runner calls this via a dynamic import guarded by a
+ * `hasTable('agent_destinations')` check — without the agent-to-agent module
+ * installed, the central table doesn't exist and the projection is skipped.
+ */
+import fs from 'fs';
+
+import { getAgentGroup } from '../../db/agent-groups.js';
+import { getMessagingGroup } from '../../db/messaging-groups.js';
+import { replaceDestinations, type DestinationRow } from '../../db/session-db.js';
+import { log } from '../../log.js';
+import { inboundDbPath, openInboundDb } from '../../session-manager.js';
+import { getDestinations } from './db/agent-destinations.js';
+
+export function writeDestinations(agentGroupId: string, sessionId: string): void {
+  const dbPath = inboundDbPath(agentGroupId, sessionId);
+  if (!fs.existsSync(dbPath)) return;
+
+  const rows = getDestinations(agentGroupId);
+  const resolved: DestinationRow[] = [];
+
+  for (const row of rows) {
+    if (row.target_type === 'channel') {
+      const mg = getMessagingGroup(row.target_id);
+      if (!mg) continue;
+      resolved.push({
+        name: row.local_name,
+        display_name: mg.name ?? row.local_name,
+        type: 'channel',
+        channel_type: mg.channel_type,
+        platform_id: mg.platform_id,
+        agent_group_id: null,
+      });
+    } else if (row.target_type === 'agent') {
+      const ag = getAgentGroup(row.target_id);
+      if (!ag) continue;
+      resolved.push({
+        name: row.local_name,
+        display_name: ag.name,
+        type: 'agent',
+        channel_type: null,
+        platform_id: null,
+        agent_group_id: ag.id,
+      });
+    }
+  }
+
+  const db = openInboundDb(agentGroupId, sessionId);
+  try {
+    replaceDestinations(db, resolved);
+  } finally {
+    db.close();
+  }
+  log.debug('Destination map written', { sessionId, count: resolved.length });
+}

package/src/modules/approvals/agent.md

@@ -0,0 +1,45 @@
+## Self-modification tools (require admin approval)
+
+Three fire-and-forget tools change your container image or config. Each sends an approval card to an admin's DM; you get notified via system chat on approve/reject.
+
+### install_packages
+
+Add apt and/or npm packages to your container image. On approval, the config is updated AND the image is rebuilt in the same step — you'll get a follow-up prompt ~5s after rebuild telling you to verify the packages are available.
+
+```
+install_packages({
+  apt: ["ripgrep", "jq"],              // names only, no version specs or flags
+  npm: ["@anthropic-ai/sdk"],          // global install
+  reason: "need rg for fast code search"
+})
+```
+
+- Max 20 packages per request.
+- Names must match strict regex (blocks shell injection via `vim; curl evil.com`).
+- On approval, the image rebuild and container restart happen automatically — there is no separate rebuild step for you to trigger.
+
+### add_mcp_server
+
+Wire an EXISTING third-party MCP server into your runtime config. You must already know the exact `command` and `args`.
+
+```
+add_mcp_server({
+  name: "github",
+  command: "npx",
+  args: ["@modelcontextprotocol/server-github"],
+  env: { GITHUB_TOKEN: "..." }
+})
+```
+
+- Does NOT install packages. Use `install_packages` first if the command isn't already available.
+- On approval, the container is killed and the next message wakes it with the new server wired up. No image rebuild — bun runs TS directly.
+
+### How approval works
+
+You won't see the admin's response in your current turn. After approval, the container is killed and next time a message arrives your container starts fresh on the new image. If a follow-up system prompt fires (as with `install_packages`), you'll see it and should act on it — verify the change, report to the user.
+
+If denied, you'll get a chat message telling you the request was rejected. Do not retry automatically; explain to the user what was denied.
+
+## Credential failures
+
+parachute-agent injects credentials into your container as env vars at spawn time, not through a runtime gateway. There's nothing for you to approve or unblock — the secret is either present (call works) or absent (call fails with 401/403). If a credential call fails, tell the user the secret is missing or expired and stop. They can add or rotate it from the `/secrets` page in the parachute-agent web UI.

package/src/modules/approvals/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Approvals module — admin approval primitive + response plumbing.
+ *
+ * Default-tier module. Ships with main. Other modules depend on it by
+ * importing `requestApproval` / `registerApprovalHandler` from this module.
+ *
+ * Registers a response handler that claims pending_approvals rows and
+ * dispatches to whatever module registered for the row's `action` string.
+ *
+ * Self-mod flows (install_packages, add_mcp_server) moved out to
+ * `src/modules/self-mod/` in PR #7 — they now register delivery actions
+ * + approval handlers via this module's public API.
+ */
+import { registerResponseHandler } from '../../response-registry.js';
+import { handleApprovalsResponse } from './response-handler.js';
+
+// Public API re-exports so consumers import from the module root.
+export { requestApproval, registerApprovalHandler, notifyAgent } from './primitive.js';
+export type { ApprovalHandler, ApprovalHandlerContext, RequestApprovalOptions } from './primitive.js';
+
+registerResponseHandler(handleApprovalsResponse);

package/src/modules/approvals/picks.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Tests for pickApprover + pickApprovalDelivery — the approver-selection
+ * half of what used to live in src/access.ts. Moved here in PR #7 alongside
+ * the approvals re-tier.
+ */
+import { beforeEach, afterEach, describe, expect, it } from 'vitest';
+
+import type { ChannelAdapter, OutboundMessage } from '../../channels/adapter.js';
+import {
+  _resetActiveAdaptersForTest,
+  _setActiveAdapterForTest,
+  initChannelAdapters,
+  registerChannelAdapter,
+  teardownChannelAdapters,
+} from '../../channels/channel-registry.js';
+import { closeDb, createAgentGroup, createMessagingGroup, initTestDb, runMigrations } from '../../db/index.js';
+import { upsertUserDm } from '../permissions/db/user-dms.js';
+import { createUser } from '../permissions/db/users.js';
+import { grantRole } from '../permissions/db/user-roles.js';
+import { pickApprovalDelivery, pickApprover } from './primitive.js';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+beforeEach(() => {
+  const db = initTestDb();
+  runMigrations(db);
+});
+
+afterEach(async () => {
+  await teardownChannelAdapters();
+  _resetActiveAdaptersForTest();
+  closeDb();
+});
+
+/**
+ * Inject a bot-pinned mock adapter directly into the active registry.
+ * Bypasses `registerChannelAdapter` / `initChannelAdapters` so a single
+ * test can mount more than one adapter on the same channel type — the
+ * factory-based mount overwrites within a channel.
+ */
+function injectBotAdapter(
+  channelType: string,
+  botId: string,
+  openDM?: (handle: string) => Promise<string>,
+): { openDMCalls: string[] } {
+  const openDMCalls: string[] = [];
+  const adapter: ChannelAdapter = {
+    name: `${channelType}:${botId}`,
+    channelType,
+    botId,
+    supportsThreads: false,
+    async setup() {},
+    async teardown() {},
+    isConnected() {
+      return true;
+    },
+    async deliver() {
+      return undefined;
+    },
+  };
+  if (openDM) {
+    adapter.openDM = async (handle: string) => {
+      openDMCalls.push(handle);
+      return openDM(handle);
+    };
+  }
+  _setActiveAdapterForTest(adapter);
+  return { openDMCalls };
+}
+
+async function mountMockAdapter(
+  channelType: string,
+  openDM?: (handle: string) => Promise<string>,
+): Promise<{ delivered: OutboundMessage[]; openDMCalls: string[] }> {
+  const delivered: OutboundMessage[] = [];
+  const openDMCalls: string[] = [];
+  const adapter: ChannelAdapter = {
+    name: channelType,
+    channelType,
+    supportsThreads: false,
+    async setup() {},
+    async teardown() {},
+    isConnected() {
+      return true;
+    },
+    async deliver(_platformId, _threadId, message) {
+      delivered.push(message);
+      return undefined;
+    },
+    async setTyping() {},
+  };
+  if (openDM) {
+    adapter.openDM = async (handle: string) => {
+      openDMCalls.push(handle);
+      return openDM(handle);
+    };
+  }
+  registerChannelAdapter(channelType, { factory: () => adapter });
+  await initChannelAdapters(() => ({
+    conversations: [],
+    onInbound: () => {},
+    onInboundEvent: () => {},
+    onMetadata: () => {},
+    onAction: () => {},
+  }));
+  return { delivered, openDMCalls };
+}
+
+function seedAgentGroup(id: string): void {
+  createAgentGroup({
+    id,
+    name: id.toUpperCase(),
+    folder: id,
+    agent_provider: null,
+    created_at: now(),
+  });
+}
+
+function seedUser(id: string, kind: string): void {
+  createUser({ id, kind, display_name: null, created_at: now() });
+}
+
+describe('pickApprover', () => {
+  beforeEach(() => {
+    seedAgentGroup('ag-1');
+    seedAgentGroup('ag-2');
+  });
+
+  it('prefers scoped admins, then globals, then owners — deduplicated', () => {
+    seedUser('u-owner', 'telegram');
+    seedUser('u-ga', 'telegram');
+    seedUser('u-sa', 'telegram');
+    grantRole({ user_id: 'u-owner', role: 'owner', agent_group_id: null, granted_by: null, granted_at: now() });
+    grantRole({ user_id: 'u-ga', role: 'admin', agent_group_id: null, granted_by: null, granted_at: now() });
+    grantRole({ user_id: 'u-sa', role: 'admin', agent_group_id: 'ag-1', granted_by: null, granted_at: now() });
+
+    expect(pickApprover('ag-1')).toEqual(['u-sa', 'u-ga', 'u-owner']);
+    expect(pickApprover('ag-2')).toEqual(['u-ga', 'u-owner']);
+    expect(pickApprover(null)).toEqual(['u-ga', 'u-owner']);
+  });
+
+  it('returns empty list when nobody is privileged', () => {
+    expect(pickApprover('ag-1')).toEqual([]);
+  });
+});
+
+describe('pickApprovalDelivery', () => {
+  beforeEach(() => {
+    seedAgentGroup('ag-1');
+  });
+
+  it('returns the first reachable approver', async () => {
+    await mountMockAdapter('telegram');
+    seedUser('telegram:111', 'telegram');
+    seedUser('telegram:222', 'telegram');
+
+    const result = await pickApprovalDelivery(['telegram:111', 'telegram:222'], 'telegram');
+    expect(result?.userId).toBe('telegram:111');
+    expect(result?.messagingGroup.platform_id).toBe('111');
+  });
+
+  it('prefers same-channel-kind approver on tie-break', async () => {
+    await mountMockAdapter('telegram');
+    await mountMockAdapter('discord', async (h) => `dm-${h}`);
+    seedUser('telegram:111', 'telegram');
+    seedUser('discord:222', 'discord');
+
+    const result = await pickApprovalDelivery(['telegram:111', 'discord:222'], 'discord');
+    expect(result?.userId).toBe('discord:222');
+  });
+
+  it('falls through to any reachable approver when none match origin', async () => {
+    await mountMockAdapter('telegram');
+    seedUser('telegram:111', 'telegram');
+
+    const result = await pickApprovalDelivery(['telegram:111'], 'discord');
+    expect(result?.userId).toBe('telegram:111');
+  });
+
+  it('returns null when nobody is reachable', async () => {
+    seedUser('telegram:111', 'telegram');
+    expect(await pickApprovalDelivery(['telegram:111'], 'telegram')).toBeNull();
+  });
+
+  /**
+   * The 3-step fallback chain (paraclaw#67 PR1):
+   *   1. same-channel approver, exact (channel, originBotId) match
+   *   2. same-channel approver, channel-default `bot_id=''` slot
+   *   3. cross-channel approver, channel-default slot
+   * `viaFallbackBot` is true whenever an originBotId was requested but
+   * the delivery landed on the channel-default slot — the caller uses
+   * that to surface "this card was routed via your default bot, not the
+   * one the inbound came from" in the body.
+   */
+  describe('bot-aware fallback chain (migration 026)', () => {
+    function seedMg(id: string, channelType: string, platformId: string): void {
+      createMessagingGroup({
+        id,
+        channel_type: channelType,
+        platform_id: platformId,
+        name: null,
+        is_group: 0,
+        unknown_sender_policy: 'strict',
+        created_at: now(),
+      });
+    }
+    function seedUserDm(userId: string, channelType: string, botId: string, mgId: string): void {
+      upsertUserDm({
+        user_id: userId,
+        channel_type: channelType,
+        bot_id: botId,
+        messaging_group_id: mgId,
+        resolved_at: now(),
+      });
+    }
+
+    it('step 1: prefers exact bot match over channel-default slot', async () => {
+      injectBotAdapter('telegram', 'primary-bot');
+      injectBotAdapter('telegram', 'secondary-bot');
+      seedUser('telegram:111', 'telegram');
+      seedMg('mg-default', 'telegram', 'telegram::111');
+      seedMg('mg-secondary', 'telegram', 'telegram:secondary-bot:111');
+      seedUserDm('telegram:111', 'telegram', '', 'mg-default');
+      seedUserDm('telegram:111', 'telegram', 'secondary-bot', 'mg-secondary');
+
+      const result = await pickApprovalDelivery(['telegram:111'], 'telegram', 'secondary-bot');
+      expect(result?.userId).toBe('telegram:111');
+      expect(result?.messagingGroup.id).toBe('mg-secondary');
+      expect(result?.viaFallbackBot).toBe(false);
+    });
+
+    it('step 2: falls back to channel-default when origin bot has no DM cached and openDM fails', async () => {
+      injectBotAdapter('telegram', 'primary-bot');
+      // secondary-bot adapter throws on openDM — Telegram's "bots can't
+      // initiate" error. Step 1 returns null, step 2 hits the cached
+      // channel-default row.
+      injectBotAdapter('telegram', 'secondary-bot', async () => {
+        throw new Error("bots can't initiate DMs");
+      });
+      seedUser('telegram:111', 'telegram');
+      seedMg('mg-default', 'telegram', 'telegram::111');
+      seedUserDm('telegram:111', 'telegram', '', 'mg-default');
+
+      const result = await pickApprovalDelivery(['telegram:111'], 'telegram', 'secondary-bot');
+      expect(result?.userId).toBe('telegram:111');
+      expect(result?.messagingGroup.id).toBe('mg-default');
+      expect(result?.viaFallbackBot).toBe(true);
+    });
+
+    it('step 2: cold-resolves the channel-default slot when nothing is cached but a default adapter exists', async () => {
+      // Single bot active for telegram. Step 1 (exact 'secondary-bot' match)
+      // can't run — no adapter for that bot id. Step 2 calls ensureUserDm
+      // with no bot id, which hits the first telegram adapter and
+      // cold-resolves through it.
+      const fallback = injectBotAdapter('telegram', 'primary-bot', async (h) => `tg:${h}`);
+      seedUser('telegram:111', 'telegram');
+
+      const result = await pickApprovalDelivery(['telegram:111'], 'telegram', 'secondary-bot');
+      expect(result?.userId).toBe('telegram:111');
+      expect(result?.viaFallbackBot).toBe(true);
+      expect(fallback.openDMCalls).toEqual(['111']);
+    });
+
+    it('step 3: cross-channel fallback when no same-channel approver is reachable', async () => {
+      // No discord adapter at all. Step 1 + 2 (same channel = discord)
+      // find no approver to reach. Step 3 walks any channel and lands on
+      // the cached telegram DM.
+      injectBotAdapter('telegram', 'primary-bot');
+      seedUser('telegram:111', 'telegram');
+      seedUser('discord:222', 'discord');
+      seedMg('mg-tg-default', 'telegram', 'telegram::111');
+      seedUserDm('telegram:111', 'telegram', '', 'mg-tg-default');
+
+      const result = await pickApprovalDelivery(['discord:222', 'telegram:111'], 'discord', 'discord-bot-1');
+      expect(result?.userId).toBe('telegram:111');
+      expect(result?.messagingGroup.id).toBe('mg-tg-default');
+      expect(result?.viaFallbackBot).toBe(true);
+    });
+
+    it('viaFallbackBot=false when no originBotId is supplied (legacy single-bot install)', async () => {
+      injectBotAdapter('telegram', 'primary-bot', async (h) => `tg:${h}`);
+      seedUser('telegram:111', 'telegram');
+
+      const result = await pickApprovalDelivery(['telegram:111'], 'telegram', null);
+      expect(result?.userId).toBe('telegram:111');
+      expect(result?.viaFallbackBot).toBe(false);
+    });
+  });
+});