@openparachute/agent 0.1.1 → 0.2.0

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

@@ -1,135 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-## 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

@@ -1,21 +0,0 @@
-/**
- * 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

@@ -1,291 +0,0 @@
-/**
- * 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);
-    });
-  });
-});