@openparachute/agent 0.1.1 → 0.2.0

package/src/modules/permissions/user-dm.ts

@@ -1,200 +0,0 @@
-/**
- * User DM resolution.
- *
- * Exposes one primitive: `ensureUserDm(userId, opts?)` returns (or lazily
- * creates) the `messaging_groups` row that the host should deliver to
- * when it wants to DM a given user. Everything that needs to cold-DM a
- * user — approvals, pairing handshakes, host notifications — goes
- * through this function.
- *
- * ## Two-class resolution
- *
- * Channels split cleanly into two classes based on whether the user id is
- * already the DM platform id:
- *
- *   - **Direct-addressable** (Telegram, WhatsApp, iMessage, email, Matrix):
- *     user handle IS the DM chat id. No adapter method needed; we just
- *     mint a messaging_group row with `platform_id = handle`.
- *
- *   - **Resolution-required** (Discord, Slack, Teams, Webex, gChat):
- *     user id and DM channel id are different. The adapter must implement
- *     `openDM(handle)`, which Chat SDK's `chat.openDM` handles for us via
- *     the bridge. The returned channel id becomes the `platform_id`.
- *
- * ## Bot-aware caching (migration 026)
- *
- * The cache PK is `(user_id, channel_type, bot_id)`. Callers that know
- * which bot the DM should reach pass `opts.botId` and get bot-pinned
- * resolution: cache reads scope to that bot, cold-resolve goes through
- * the live adapter for `(channel, botId)` (not just the first adapter
- * for that channel), and the resulting cache row is written under that
- * bot's id.
- *
- * Callers that don't pass a bot id get the legacy "first adapter for
- * this channel" behavior, with cache rows under `bot_id = ''` — the
- * configurable channel-default slot. The settings UI lets the operator
- * point that slot at a specific bot's DM, and `pickApprovalDelivery`
- * falls through to it when an exact-bot resolve fails.
- *
- * ## Caching
- *
- * Successful resolutions are persisted in `user_dms`. The cache survives
- * restarts; first-time DMs on a given `(channel, bot)` pair pay one
- * `openDM` round trip, everyone after is a pure DB read.
- *
- * The underlying platform APIs (`POST /users/@me/channels` on Discord,
- * `conversations.open` on Slack, etc.) are idempotent and return the
- * same channel on repeated calls, so re-resolving after a cache miss is
- * always safe — worst case we round-trip redundantly.
- */
-import { getChannelAdapter, getChannelAdapterByBotId } from '../../channels/channel-registry.js';
-import { getMessagingGroup, getMessagingGroupByPlatform, createMessagingGroup } from '../../db/messaging-groups.js';
-import { log } from '../../log.js';
-import type { ChannelAdapter } from '../../channels/adapter.js';
-import type { MessagingGroup, User } from '../../types.js';
-import { getUser } from './db/users.js';
-import { getUserDm, upsertUserDm } from './db/user-dms.js';
-
-export interface EnsureUserDmOptions {
-  /**
-   * Pin the resolution to a specific bot. When set, the cache is read /
-   * written under that exact bot id and cold-resolve uses the adapter
-   * registered for `(channelType, botId)`. When omitted (or empty
-   * string), the legacy "first adapter for this channel" path runs and
-   * the cache row lands under `bot_id = ''` (the configurable
-   * channel-default slot).
-   */
-  botId?: string | null;
-}
-
-/**
- * Return a messaging_group usable to DM this user, creating it lazily if
- * needed. Returns null when:
- *   - the user id isn't namespaced (no `kind:handle` prefix)
- *   - the user's channel has no adapter registered (or, when `opts.botId`
- *     is set, no adapter is registered for that exact `(channel, bot)`)
- *   - the channel needs openDM but its adapter doesn't implement it
- *   - openDM throws (platform error, user blocked bot, the bot can't
- *     initiate a DM until the user has messaged it first, etc.)
- *
- * Callers should treat null as "this user is unreachable on this
- * channel + bot pair." `pickApprovalDelivery` translates that into a
- * channel-default fallback before giving up entirely.
- */
-export async function ensureUserDm(userId: string, opts?: EnsureUserDmOptions): Promise<MessagingGroup | null> {
-  const user = getUser(userId);
-  if (!user) {
-    log.warn('ensureUserDm: user not found', { userId });
-    return null;
-  }
-
-  const { channelType, handle } = parseUserId(user);
-  if (!channelType || !handle) {
-    log.warn('ensureUserDm: user id not namespaced', { userId });
-    return null;
-  }
-
-  const botId = opts?.botId ?? '';
-
-  // Cache hit: existing user_dms row → load and return the messaging_group.
-  const cached = getUserDm(userId, channelType, botId);
-  if (cached) {
-    const mg = getMessagingGroup(cached.messaging_group_id);
-    if (mg) return mg;
-    // Row points to a deleted messaging_group — fall through and re-resolve.
-    log.warn('ensureUserDm: cached row references missing messaging_group, re-resolving', {
-      userId,
-      botId,
-      messagingGroupId: cached.messaging_group_id,
-    });
-  }
-
-  // Cache miss: pick the adapter. With a bot id we MUST use that exact
-  // bot's adapter — falling back to "any adapter for this channel" would
-  // re-introduce the bug Proposal C is fixing (cross-bot delivery).
-  const adapter = botId ? getChannelAdapterByBotId(channelType, botId) : getChannelAdapter(channelType);
-  if (!adapter) {
-    log.warn('ensureUserDm: no adapter for channel/bot', { channelType, botId });
-    return null;
-  }
-
-  const dmPlatformId = await resolveDmPlatformId(adapter, channelType, handle);
-  if (!dmPlatformId) return null;
-
-  // Find-or-create the underlying messaging_group. A DM we received
-  // earlier may already have a row matching (channel_type, platform_id).
-  const now = new Date().toISOString();
-  let mg = getMessagingGroupByPlatform(channelType, dmPlatformId);
-  if (!mg) {
-    const mgId = `mg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    mg = {
-      id: mgId,
-      channel_type: channelType,
-      platform_id: dmPlatformId,
-      name: user.display_name,
-      is_group: 0,
-      unknown_sender_policy: 'strict',
-      created_at: now,
-    };
-    createMessagingGroup(mg);
-    log.info('ensureUserDm: created DM messaging_group', {
-      userId,
-      channelType,
-      botId,
-      messagingGroupId: mgId,
-    });
-  }
-
-  upsertUserDm({
-    user_id: userId,
-    channel_type: channelType,
-    bot_id: botId,
-    messaging_group_id: mg.id,
-    resolved_at: now,
-  });
-
-  return mg;
-}
-
-/**
- * Call the adapter's openDM if it has one; otherwise fall through to using
- * the handle directly. Returns null if openDM throws (platform-side
- * refusal — Telegram bots can't DM first, Discord blocked-by-recipient,
- * etc.).
- */
-async function resolveDmPlatformId(
-  adapter: ChannelAdapter,
-  channelType: string,
-  handle: string,
-): Promise<string | null> {
-  if (!adapter.openDM) {
-    // Direct-addressable channel — handle doubles as the DM chat id.
-    return handle;
-  }
-  try {
-    return await adapter.openDM(handle);
-  } catch (err) {
-    log.error('ensureUserDm: adapter.openDM failed', {
-      channelType,
-      botId: adapter.botId ?? null,
-      handle,
-      err,
-    });
-    return null;
-  }
-}
-
-function parseUserId(user: User): { channelType: string; handle: string } | { channelType: null; handle: null } {
-  const idx = user.id.indexOf(':');
-  if (idx < 0) return { channelType: null, handle: null };
-  const prefix = user.id.slice(0, idx);
-  const handle = user.id.slice(idx + 1);
-  if (!prefix || !handle) return { channelType: null, handle: null };
-  // Teams user IDs use a `29:` prefix, not `teams:`. When the id prefix
-  // isn't a registered adapter, fall back to user.kind and treat the full
-  // id as the handle.
-  if (!getChannelAdapter(prefix) && user.kind && getChannelAdapter(user.kind)) {
-    return { channelType: user.kind, handle: user.id };
-  }
-  return { channelType: prefix, handle };
-}

package/src/modules/provider-credentials/db.ts

@@ -1,121 +0,0 @@
-/**
- * `provider_credentials` row helpers.
- *
- * The PK column doubles as a sentinel slot — id `'__default__'` is the
- * install-wide row; Phase 2 will add real `agent_group_id` rows alongside.
- *
- * Encryption: `api_key_encrypted` is AES-GCM ciphertext (HKDF-derived
- * key, info `paraclaw.provider-credentials.v1`). Plaintext only crosses
- * this module's boundary at put/get time.
- *
- * ⚠ The `paraclaw.` prefix in the HKDF info string is a cryptographic
- * domain separator and is frozen across the paraclaw → parachute-agent
- * rename. Renaming it derives a different key and renders existing
- * ciphertext undecryptable. The brand sweep does not touch these bytes.
- */
-import { getDb } from '../../db/connection.js';
-import { decryptSecret, deriveKey, encryptSecret } from '../../secrets/crypto.js';
-import { loadOrCreateMasterKey } from '../../secrets/master-key.js';
-
-export const DEFAULT_SCOPE_ID = '__default__';
-const PROVIDER_CREDS_INFO = 'paraclaw.provider-credentials.v1';
-
-export type ProviderSource = 'claude_setup_token' | 'anthropic_api_key' | 'external_server';
-
-export interface ProviderCredentialsRow {
-  agent_group_id: string;
-  source: ProviderSource;
-  api_key_encrypted: string | null;
-  server_url: string | null;
-  updated_at: string;
-}
-
-export interface ProviderCredentialsPlaintext {
-  agent_group_id: string;
-  source: ProviderSource;
-  /**
-   * Plaintext secret. For `claude_setup_token` this is the OAuth token
-   * (`sk-ant-oat01-...`). For `anthropic_api_key` and `external_server`
-   * it's the API key. Null when unset.
-   */
-  apiKey: string | null;
-  serverUrl: string | null;
-  updatedAt: string;
-}
-
-function key(): Buffer {
-  return deriveKey(loadOrCreateMasterKey(), PROVIDER_CREDS_INFO);
-}
-
-export function getProviderCredentialsRow(scopeId: string = DEFAULT_SCOPE_ID): ProviderCredentialsRow | undefined {
-  return getDb()
-    .prepare<ProviderCredentialsRow>('SELECT * FROM provider_credentials WHERE agent_group_id = ?')
-    .get(scopeId);
-}
-
-export function readProviderCredentials(scopeId: string = DEFAULT_SCOPE_ID): ProviderCredentialsPlaintext | undefined {
-  const row = getProviderCredentialsRow(scopeId);
-  if (!row) return undefined;
-  const k = key();
-  return {
-    agent_group_id: row.agent_group_id,
-    source: row.source,
-    apiKey: row.api_key_encrypted ? decryptSecret(row.api_key_encrypted, k) : null,
-    serverUrl: row.server_url,
-    updatedAt: row.updated_at,
-  };
-}
-
-export interface PutProviderCredentialsInput {
-  // Required so a future caller can't silently overwrite the install-wide
-  // row by forgetting the scope. Pass `DEFAULT_SCOPE_ID` explicitly when
-  // you mean the install-wide credential.
-  scopeId: string;
-  source: ProviderSource;
-  apiKey?: string | null;
-  serverUrl?: string | null;
-}
-
-/**
- * Upsert the row for the given scope. Plaintext fields are encrypted
- * here. Pass `null` to clear a field; pass `undefined` to leave it
- * unchanged (caller-side merge — we read-modify-write).
- */
-export function putProviderCredentials(input: PutProviderCredentialsInput): void {
-  const { scopeId } = input;
-  const existing = getProviderCredentialsRow(scopeId);
-  const k = key();
-  const api_key_encrypted =
-    input.apiKey === undefined
-      ? (existing?.api_key_encrypted ?? null)
-      : input.apiKey === null
-        ? null
-        : encryptSecret(input.apiKey, k);
-  const server_url = input.serverUrl === undefined ? (existing?.server_url ?? null) : input.serverUrl;
-  const updated_at = new Date().toISOString();
-
-  getDb()
-    .prepare(
-      `INSERT INTO provider_credentials
-         (agent_group_id, source, api_key_encrypted, server_url, updated_at)
-       VALUES
-         (@agent_group_id, @source, @api_key_encrypted, @server_url, @updated_at)
-       ON CONFLICT (agent_group_id) DO UPDATE SET
-         source = excluded.source,
-         api_key_encrypted = excluded.api_key_encrypted,
-         server_url = excluded.server_url,
-         updated_at = excluded.updated_at`,
-    )
-    .run({
-      agent_group_id: scopeId,
-      source: input.source,
-      api_key_encrypted,
-      server_url,
-      updated_at,
-    });
-}
-
-export function deleteProviderCredentials(scopeId: string = DEFAULT_SCOPE_ID): boolean {
-  const r = getDb().prepare('DELETE FROM provider_credentials WHERE agent_group_id = ?').run(scopeId);
-  return r.changes > 0;
-}

package/src/modules/provider-credentials/index.ts

@@ -1,12 +0,0 @@
-export {
-  DEFAULT_SCOPE_ID,
-  deleteProviderCredentials,
-  getProviderCredentialsRow,
-  putProviderCredentials,
-  readProviderCredentials,
-  type ProviderCredentialsPlaintext,
-  type ProviderCredentialsRow,
-  type ProviderSource,
-  type PutProviderCredentialsInput,
-} from './db.js';
-export { getProviderCredentialsForSpawn, type ProviderSpawnEnvelope } from './spawn.js';

package/src/modules/provider-credentials/spawn.test.ts

@@ -1,206 +0,0 @@
-import fs from 'fs';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-vi.mock('../../config.js', async () => {
-  const actual = await vi.importActual('../../config.js');
-  return { ...actual, DATA_DIR: '/tmp/paraclaw-test-provider-credentials' };
-});
-
-const TEST_DIR = '/tmp/paraclaw-test-provider-credentials';
-
-describe('getProviderCredentialsForSpawn', () => {
-  beforeEach(async () => {
-    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
-    fs.mkdirSync(TEST_DIR, { recursive: true });
-    vi.resetModules();
-    const { initTestDb, runMigrations } = await import('../../db/index.js');
-    const db = initTestDb();
-    runMigrations(db);
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('returns empty envelope when no row exists', async () => {
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBeNull();
-    expect(env.env).toEqual({});
-    expect(env.files).toEqual({});
-    expect(env.suppressSecretEnvKeys.size).toBe(0);
-  });
-
-  it('claude_setup_token → injects CLAUDE_CODE_OAUTH_TOKEN env, suppresses ANTHROPIC_API_KEY + ANTHROPIC_AUTH_TOKEN', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'claude_setup_token', apiKey: 'sk-ant-oat01-paste' });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBe('claude_setup_token');
-    expect(env.env).toEqual({ CLAUDE_CODE_OAUTH_TOKEN: 'sk-ant-oat01-paste' });
-    expect(env.files).toEqual({});
-    expect(env.suppressSecretEnvKeys.has('ANTHROPIC_API_KEY')).toBe(true);
-    expect(env.suppressSecretEnvKeys.has('ANTHROPIC_AUTH_TOKEN')).toBe(true);
-  });
-
-  it('claude_setup_token → empty env when token missing', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'claude_setup_token', apiKey: null });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBe('claude_setup_token');
-    expect(env.env).toEqual({});
-  });
-
-  it('anthropic_api_key → injects ANTHROPIC_API_KEY env, no files, no suppress', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'sk-ant-api03-test' });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBe('anthropic_api_key');
-    expect(env.env).toEqual({ ANTHROPIC_API_KEY: 'sk-ant-api03-test' });
-    expect(env.files).toEqual({});
-    expect(env.suppressSecretEnvKeys.size).toBe(0);
-  });
-
-  it('external_server → injects ANTHROPIC_API_KEY + ANTHROPIC_BASE_URL', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({
-      scopeId: DEFAULT_SCOPE_ID,
-      source: 'external_server',
-      apiKey: 'or-key',
-      serverUrl: 'https://openrouter.ai/api/v1',
-    });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBe('external_server');
-    expect(env.env).toEqual({
-      ANTHROPIC_API_KEY: 'or-key',
-      ANTHROPIC_BASE_URL: 'https://openrouter.ai/api/v1',
-    });
-  });
-
-  it('external_server → empty env when key or url missing', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'external_server', apiKey: 'or-key', serverUrl: null });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-1');
-    expect(env.source).toBe('external_server');
-    expect(env.env).toEqual({});
-  });
-
-  it('per-group override wins over default (paraclaw#86)', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
-    putProviderCredentials({
-      scopeId: 'ag-special',
-      source: 'external_server',
-      apiKey: 'override-key',
-      serverUrl: 'https://override.test',
-    });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-special');
-    expect(env.source).toBe('external_server');
-    expect(env.resolvedScope).toBe('group');
-    expect(env.env).toEqual({
-      ANTHROPIC_API_KEY: 'override-key',
-      ANTHROPIC_BASE_URL: 'https://override.test',
-    });
-  });
-
-  it('falls back to default when no per-group override exists (paraclaw#86)', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-no-override');
-    expect(env.source).toBe('anthropic_api_key');
-    expect(env.resolvedScope).toBe('default');
-    expect(env.env).toEqual({ ANTHROPIC_API_KEY: 'install-default-key' });
-  });
-
-  it("one group's override does not leak into another group (paraclaw#86)", async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
-    putProviderCredentials({
-      scopeId: 'ag-private',
-      source: 'claude_setup_token',
-      apiKey: 'sk-ant-oat01-private',
-    });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const privateEnv = getProviderCredentialsForSpawn('ag-private');
-    expect(privateEnv.resolvedScope).toBe('group');
-    expect(privateEnv.env).toEqual({ CLAUDE_CODE_OAUTH_TOKEN: 'sk-ant-oat01-private' });
-
-    const otherEnv = getProviderCredentialsForSpawn('ag-other');
-    expect(otherEnv.resolvedScope).toBe('default');
-    expect(otherEnv.env).toEqual({ ANTHROPIC_API_KEY: 'install-default-key' });
-  });
-
-  it('group override with empty secret slot still wins (paraclaw#86)', async () => {
-    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
-    putProviderCredentials({ scopeId: 'ag-broken', source: 'claude_setup_token', apiKey: null });
-
-    const { getProviderCredentialsForSpawn } = await import('./spawn.js');
-    const env = getProviderCredentialsForSpawn('ag-broken');
-    expect(env.source).toBe('claude_setup_token');
-    expect(env.resolvedScope).toBe('group');
-    expect(env.env).toEqual({});
-  });
-});
-
-describe('provider_credentials db round-trip', () => {
-  beforeEach(async () => {
-    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
-    fs.mkdirSync(TEST_DIR, { recursive: true });
-    vi.resetModules();
-    const { initTestDb, runMigrations } = await import('../../db/index.js');
-    const db = initTestDb();
-    runMigrations(db);
-  });
-
-  it('encrypts api_key at rest, decrypts on read', async () => {
-    const { putProviderCredentials, readProviderCredentials, getProviderCredentialsRow, DEFAULT_SCOPE_ID } =
-      await import('./db.js');
-    putProviderCredentials({
-      scopeId: DEFAULT_SCOPE_ID,
-      source: 'anthropic_api_key',
-      apiKey: 'sk-ant-api03-secret',
-    });
-
-    const raw = getProviderCredentialsRow();
-    expect(raw?.api_key_encrypted).not.toBe('sk-ant-api03-secret');
-    expect(raw?.api_key_encrypted).toBeTruthy();
-
-    const plain = readProviderCredentials();
-    expect(plain?.apiKey).toBe('sk-ant-api03-secret');
-  });
-
-  it('upsert preserves unspecified fields (undefined = no-op, null = clear)', async () => {
-    const { putProviderCredentials, readProviderCredentials, DEFAULT_SCOPE_ID } = await import('./db.js');
-    putProviderCredentials({
-      scopeId: DEFAULT_SCOPE_ID,
-      source: 'external_server',
-      apiKey: 'k1',
-      serverUrl: 'https://a.test',
-    });
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'external_server', serverUrl: 'https://b.test' });
-
-    const plain = readProviderCredentials();
-    expect(plain?.apiKey).toBe('k1');
-    expect(plain?.serverUrl).toBe('https://b.test');
-
-    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'external_server', apiKey: null });
-    const cleared = readProviderCredentials();
-    expect(cleared?.apiKey).toBeNull();
-    expect(cleared?.serverUrl).toBe('https://b.test');
-  });
-});

package/src/modules/provider-credentials/spawn.ts

@@ -1,114 +0,0 @@
-/**
- * Resolve the credentials the host should hand the agent container at
- * spawn time. The container-runner calls `getProviderCredentialsForSpawn`
- * once per spawn and acts on the returned envelope:
- *
- *   - `env`: extra `-e KEY=VALUE` pairs to add to the container args.
- *   - `files`: file-content pairs to write into the per-group `.claude-shared`
- *              dir so they appear inside the container under `/home/node/.claude`.
- *              (Reserved for future sources; setup-token / api-key / external-server
- *              all inject via env vars only.)
- *   - `suppressSecretEnvKeys`: paraclaw secrets named here are dropped from
- *              the spawn's secret bag. Used so a residual `ANTHROPIC_API_KEY`
- *              secret can't override the operator's chosen `claude_setup_token`
- *              source — Claude Code's auth precedence puts ANTHROPIC_AUTH_TOKEN
- *              and ANTHROPIC_API_KEY ahead of CLAUDE_CODE_OAUTH_TOKEN.
- *
- * Source-specific behavior:
- *   - claude_setup_token: env `CLAUDE_CODE_OAUTH_TOKEN=<token>`. Suppress
- *     `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` from the secret bag.
- *   - anthropic_api_key: env `ANTHROPIC_API_KEY=<plaintext>`.
- *   - external_server: env `ANTHROPIC_API_KEY=<plaintext>` + `ANTHROPIC_BASE_URL=<server_url>`.
- *
- * Two-tier resolution (paraclaw#86): if a row keyed by the spawn's
- * `agentGroupId` exists, it wins; otherwise the install-wide default
- * (`__default__`) row is used. A group row with the secret slot empty
- * still wins — clear-the-override is a deliberate UI action that
- * deletes the row, not one that blanks out the secret.
- */
-import { log } from '../../log.js';
-import { DEFAULT_SCOPE_ID, readProviderCredentials, type ProviderSource } from './db.js';
-
-export interface ProviderSpawnEnvelope {
-  /** Source we resolved. `null` means no row + no auto-fallback — caller emits a warning. */
-  source: ProviderSource | null;
-  /** Which scope the resolved row came from — `'group'` if the per-group override won, `'default'` if it fell back. */
-  resolvedScope: 'group' | 'default' | null;
-  env: Record<string, string>;
-  /** Filename → contents. Filenames are joined under the per-group `.claude-shared/` dir. */
-  files: Record<string, string>;
-  /** Paraclaw-secret env-var names to suppress for this spawn. */
-  suppressSecretEnvKeys: Set<string>;
-}
-
-/**
- * Resolve the spawn envelope for an agent group. Reads the per-group
- * override first, then falls back to the install-wide default. Pure of
- * filesystem writes; the container-runner is the one that lays down
- * `files` on disk and threads `env` into spawn args.
- */
-export function getProviderCredentialsForSpawn(agentGroupId: string): ProviderSpawnEnvelope {
-  const empty: ProviderSpawnEnvelope = {
-    source: null,
-    resolvedScope: null,
-    env: {},
-    files: {},
-    suppressSecretEnvKeys: new Set(),
-  };
-
-  const groupRow = agentGroupId !== DEFAULT_SCOPE_ID ? readProviderCredentials(agentGroupId) : undefined;
-  const row = groupRow ?? readProviderCredentials(DEFAULT_SCOPE_ID);
-  const resolvedScope: 'group' | 'default' | null = groupRow ? 'group' : row ? 'default' : null;
-  if (!row) return empty;
-
-  switch (row.source) {
-    case 'claude_setup_token': {
-      if (!row.apiKey) {
-        log.warn('claude_setup_token selected but no token stored', { agentGroupId, resolvedScope });
-        return { ...empty, source: 'claude_setup_token', resolvedScope };
-      }
-      return {
-        source: 'claude_setup_token',
-        resolvedScope,
-        env: { CLAUDE_CODE_OAUTH_TOKEN: row.apiKey },
-        files: {},
-        // Claude Code's auth precedence: ANTHROPIC_AUTH_TOKEN and
-        // ANTHROPIC_API_KEY both win over CLAUDE_CODE_OAUTH_TOKEN. If
-        // either is sitting in the paraclaw secret bag, the operator's
-        // chosen setup-token source would be silently overridden.
-        suppressSecretEnvKeys: new Set(['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN']),
-      };
-    }
-    case 'anthropic_api_key': {
-      if (!row.apiKey) {
-        log.warn('anthropic_api_key selected but no key stored', { agentGroupId, resolvedScope });
-        return { ...empty, source: 'anthropic_api_key', resolvedScope };
-      }
-      return {
-        source: 'anthropic_api_key',
-        resolvedScope,
-        env: { ANTHROPIC_API_KEY: row.apiKey },
-        files: {},
-        suppressSecretEnvKeys: new Set(),
-      };
-    }
-    case 'external_server': {
-      if (!row.apiKey || !row.serverUrl) {
-        log.warn('external_server selected but key or url missing', {
-          agentGroupId,
-          resolvedScope,
-          hasKey: row.apiKey != null,
-          hasUrl: row.serverUrl != null,
-        });
-        return { ...empty, source: 'external_server', resolvedScope };
-      }
-      return {
-        source: 'external_server',
-        resolvedScope,
-        env: { ANTHROPIC_API_KEY: row.apiKey, ANTHROPIC_BASE_URL: row.serverUrl },
-        files: {},
-        suppressSecretEnvKeys: new Set(),
-      };
-    }
-  }
-}