@openparachute/agent 0.1.0

package/src/modules/scheduling/recurrence.ts

@@ -0,0 +1,54 @@
+/**
+ * Sweep hook for recurring tasks.
+ *
+ * Every sweep tick, find `messages_in` rows that are `completed` AND still
+ * have a `recurrence` cron expression. For each, compute the next run via
+ * cron-parser, insert a fresh pending row (copying series_id forward), then
+ * clear the recurrence on the original so it isn't re-cloned next tick.
+ *
+ * Called from `src/host-sweep.ts` inside `MODULE-HOOK:scheduling-recurrence`.
+ * When scheduling ships inline (current state through PR #7), the hook is a
+ * direct dynamic import. When scheduling moves to the modules branch in
+ * PR #8, the install skill re-fills the marker on install.
+ */
+import type { Database } from '../../db/connection.js';
+
+import { TIMEZONE } from '../../config.js';
+import { log } from '../../log.js';
+import type { Session } from '../../types.js';
+import { clearRecurrence, getCompletedRecurring, insertRecurrence } from './db.js';
+
+export async function handleRecurrence(inDb: Database, session: Session): Promise<void> {
+  const recurring = getCompletedRecurring(inDb);
+
+  for (const msg of recurring) {
+    try {
+      const { CronExpressionParser } = await import('cron-parser');
+      // Interpret the cron expression in the user's timezone. v1 did this
+      // (src/v1/task-scheduler.ts:20-49); without it, a task written "0 9 * * *"
+      // by an agent running in a user's local TZ fires at 09:00 UTC instead of
+      // 09:00 user-local.
+      const interval = CronExpressionParser.parse(msg.recurrence, { tz: TIMEZONE });
+      const nextRun = interval.next().toISOString();
+      const prefix = msg.kind === 'task' ? 'task' : 'msg';
+      const newId = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+      insertRecurrence(inDb, msg, newId, nextRun);
+      clearRecurrence(inDb, msg.id);
+
+      log.info('Inserted next recurrence', {
+        originalId: msg.id,
+        newId,
+        seriesId: msg.series_id,
+        nextRun,
+        sessionId: session.id,
+      });
+    } catch (err) {
+      log.error('Failed to compute next recurrence', {
+        messageId: msg.id,
+        recurrence: msg.recurrence,
+        err,
+      });
+    }
+  }
+}

package/src/modules/self-mod/agent.md

@@ -0,0 +1,30 @@
+# Self-modification
+
+You can install additional OS or npm packages or add new MCP servers — but
+only with admin approval.
+
+## Tools
+
+- `install_packages({ apt?: string[], npm?: string[], reason?: string })` —
+  adds the listed packages to your container config, rebuilds the image,
+  and restarts your container, all in a single admin approval step.
+  Package names are validated strictly (`[a-z0-9._+-]` for apt, standard
+  npm naming with optional scope). Max 20 packages per request.
+
+- `add_mcp_server({ name, command, args?, env? })` — adds a new MCP server
+  to your container config and restarts the container so the new server
+  is wired up on the next message. No image rebuild is required (bun runs
+  TS directly).
+
+## Flow
+
+You call one of these tools → the host asks an admin via DM → admin approves
+or rejects. On approve, the config is applied, the image is rebuilt if
+needed, and the container is killed; the host respawns it on the next
+message. You'll get a system chat message confirming the outcome (either
+"Packages installed..." or a failure reason).
+
+On reject you'll see "Your X request was rejected by admin."
+
+If no admin is configured or reachable, the request fails immediately with
+a chat notification explaining why.

package/src/modules/self-mod/apply.ts

@@ -0,0 +1,85 @@
+/**
+ * Approval handlers for self-modification actions.
+ *
+ * The approvals module calls these when an admin clicks Approve on a
+ * pending_approvals row whose action matches. Each handler mutates the
+ * container config, rebuilds/kills the container as needed, and lets the
+ * host sweep respawn it on the new image on the next message.
+ *
+ * install_packages: rebuild image + kill container (apt/npm global installs
+ *   must be baked into the image layer).
+ * add_mcp_server: kill container only — bun runs TS directly, so a pure
+ *   MCP wiring change needs nothing more than a process restart.
+ */
+import { updateContainerConfig } from '../../container-config.js';
+import { buildAgentGroupImage, killContainer } from '../../container-runner.js';
+import { getAgentGroup } from '../../db/agent-groups.js';
+import { log } from '../../log.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import type { ApprovalHandler } from '../approvals/index.js';
+
+export const applyInstallPackages: ApprovalHandler = async ({ session, payload, userId, notify }) => {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) {
+    notify('install_packages approved but agent group missing.');
+    return;
+  }
+  updateContainerConfig(agentGroup.folder, (cfg) => {
+    if (payload.apt) cfg.packages.apt.push(...(payload.apt as string[]));
+    if (payload.npm) cfg.packages.npm.push(...(payload.npm as string[]));
+  });
+
+  const pkgs = [
+    ...((payload.apt as string[] | undefined) || []),
+    ...((payload.npm as string[] | undefined) || []),
+  ].join(', ');
+  log.info('Package install approved', { agentGroupId: session.agent_group_id, userId });
+  try {
+    await buildAgentGroupImage(session.agent_group_id);
+    killContainer(session.id, 'rebuild applied');
+    // Schedule a follow-up prompt a few seconds after kill so the host sweep
+    // respawns the container on the new image and the agent verifies + reports.
+    writeSessionMessage(session.agent_group_id, session.id, {
+      id: `appr-note-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      kind: 'chat',
+      timestamp: new Date().toISOString(),
+      platformId: session.agent_group_id,
+      channelType: 'agent',
+      threadId: null,
+      content: JSON.stringify({
+        text: `Packages installed (${pkgs}) and container rebuilt. Verify the new packages are available (e.g. run them or check versions) and report the result to the user.`,
+        sender: 'system',
+        senderId: 'system',
+      }),
+      processAfter: new Date(Date.now() + 5000)
+        .toISOString()
+        .replace('T', ' ')
+        .replace(/\.\d+Z$/, ''),
+    });
+    log.info('Container rebuild completed (bundled with install)', { agentGroupId: session.agent_group_id });
+  } catch (e) {
+    notify(
+      `Packages added to config (${pkgs}) but rebuild failed: ${e instanceof Error ? e.message : String(e)}. Tell the user — an admin will need to retry the install_packages request or inspect the build logs.`,
+    );
+    log.error('Bundled rebuild failed after install approval', { agentGroupId: session.agent_group_id, err: e });
+  }
+};
+
+export const applyAddMcpServer: ApprovalHandler = async ({ session, payload, userId, notify }) => {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) {
+    notify('add_mcp_server approved but agent group missing.');
+    return;
+  }
+  updateContainerConfig(agentGroup.folder, (cfg) => {
+    cfg.mcpServers[payload.name as string] = {
+      command: payload.command as string,
+      args: (payload.args as string[]) || [],
+      env: (payload.env as Record<string, string>) || {},
+    };
+  });
+
+  killContainer(session.id, 'mcp server added');
+  notify(`MCP server "${payload.name}" added. Your container will restart with it on the next message.`);
+  log.info('MCP server add approved', { agentGroupId: session.agent_group_id, userId });
+};

package/src/modules/self-mod/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Self-modification module — admin-approved container mutations.
+ *
+ * Optional tier. Depends on the approvals default module for the request/
+ * handler plumbing. On install the module registers:
+ *   - Two delivery actions (install_packages, add_mcp_server) that validate
+ *     input and queue an approval via requestApproval().
+ *   - Two matching approval handlers that run on approve and perform the
+ *     complete follow-up:
+ *       install_packages → update container.json, rebuild image, kill
+ *         container (next wake respawns on the new image), schedule a
+ *         verify-and-report follow-up prompt.
+ *       add_mcp_server → update container.json, kill container. No image
+ *         rebuild — bun runs TS directly, so the new MCP server is wired
+ *         by the next container start.
+ *
+ * Without this module: the MCP tools in the container still write outbound
+ * system messages with these actions, but delivery logs "Unknown system
+ * action" and drops them. Admin never sees a card; nothing changes.
+ */
+import { registerDeliveryAction } from '../../delivery.js';
+import { registerApprovalHandler } from '../approvals/index.js';
+import { applyAddMcpServer, applyInstallPackages } from './apply.js';
+import { handleAddMcpServer, handleInstallPackages } from './request.js';
+
+registerDeliveryAction('install_packages', handleInstallPackages);
+registerDeliveryAction('add_mcp_server', handleAddMcpServer);
+
+registerApprovalHandler('install_packages', applyInstallPackages);
+registerApprovalHandler('add_mcp_server', applyAddMcpServer);

package/src/modules/self-mod/project.md

@@ -0,0 +1,39 @@
+# Self-mod module
+
+Optional-tier module that gives agents admin-gated self-modification:
+installing OS/npm packages and registering new MCP servers. Both paths go
+through the approvals module's request primitive — no unapproved changes
+ever land. The rebuild+restart (or restart-only) follow-up is bundled into
+the approval handler itself — there is no separate "request rebuild" step.
+
+## What this module adds
+
+- Two delivery actions (`install_packages`, `add_mcp_server`) that the
+  container's self-mod MCP tools write into outbound.db. On the host, each
+  handler validates input and queues an approval via
+  `approvals.requestApproval()`.
+- Two matching approval handlers that run on approve:
+  - `install_packages` → update `container.json`, rebuild the image via
+    `buildAgentGroupImage`, and kill the container so the host sweep
+    respawns it on the new image. Also schedules a verify-and-report
+    follow-up prompt ~5 s after kill.
+  - `add_mcp_server` → update `container.json` and kill the container.
+    No image rebuild — bun runs TS directly, so the new MCP wiring is
+    picked up on the next container start.
+
+## Dependency
+
+Self-mod depends on the approvals default module for:
+- `requestApproval()` to enqueue admin confirmation cards
+- `registerApprovalHandler(action, handler)` to run orchestration on approve
+- `notifyAgent()` to send failure feedback back to the requesting agent
+
+It also calls core's `buildAgentGroupImage`, `killContainer`, and
+`updateContainerConfig`.
+
+## Removing the module
+
+Delete `src/modules/self-mod/` and its import line in `src/modules/index.ts`.
+The container's self-mod MCP tools will still write outbound system messages,
+but core delivery will log `"Unknown system action"` and drop them — no
+admin card, no container mutation.

package/src/modules/self-mod/request.ts

@@ -0,0 +1,91 @@
+/**
+ * Delivery-action handlers for agent-initiated self-modification requests.
+ *
+ * Two actions the container can write into messages_out (via the self-mod
+ * MCP tools): install_packages, add_mcp_server. Each one validates input
+ * and queues an approval request. The admin's approval triggers the
+ * matching approval handler in ./apply.ts, which also performs the
+ * required follow-up (rebuild+restart for install_packages, restart-only
+ * for add_mcp_server).
+ *
+ * Host-side sanitization for install_packages is defense-in-depth — the MCP
+ * tool validates first. Both layers matter: the DB row carries the payload
+ * verbatim through to shell exec on apply.
+ */
+import { getAgentGroup } from '../../db/agent-groups.js';
+import { log } from '../../log.js';
+import type { Session } from '../../types.js';
+import { notifyAgent, requestApproval } from '../approvals/index.js';
+
+export async function handleInstallPackages(content: Record<string, unknown>, session: Session): Promise<void> {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) {
+    notifyAgent(session, 'install_packages failed: agent group not found.');
+    return;
+  }
+
+  const apt = (content.apt as string[]) || [];
+  const npm = (content.npm as string[]) || [];
+  const reason = (content.reason as string) || '';
+
+  const APT_RE = /^[a-z0-9][a-z0-9._+-]*$/;
+  const NPM_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+  const MAX_PACKAGES = 20;
+  if (apt.length + npm.length === 0) {
+    notifyAgent(session, 'install_packages failed: at least one apt or npm package is required.');
+    return;
+  }
+  if (apt.length + npm.length > MAX_PACKAGES) {
+    notifyAgent(session, `install_packages failed: max ${MAX_PACKAGES} packages per request.`);
+    return;
+  }
+  const invalidApt = apt.find((p) => !APT_RE.test(p));
+  if (invalidApt) {
+    notifyAgent(session, `install_packages failed: invalid apt package name "${invalidApt}".`);
+    log.warn('install_packages: invalid apt package rejected', { pkg: invalidApt });
+    return;
+  }
+  const invalidNpm = npm.find((p) => !NPM_RE.test(p));
+  if (invalidNpm) {
+    notifyAgent(session, `install_packages failed: invalid npm package name "${invalidNpm}".`);
+    log.warn('install_packages: invalid npm package rejected', { pkg: invalidNpm });
+    return;
+  }
+
+  const packageList = [...apt.map((p) => `apt: ${p}`), ...npm.map((p) => `npm: ${p}`)].join(', ');
+  await requestApproval({
+    session,
+    agentName: agentGroup.name,
+    action: 'install_packages',
+    payload: { apt, npm, reason },
+    title: 'Install Packages Request',
+    question: `Agent "${agentGroup.name}" is attempting to install a package + rebuild container:\n${packageList}${reason ? `\nReason: ${reason}` : ''}`,
+  });
+}
+
+export async function handleAddMcpServer(content: Record<string, unknown>, session: Session): Promise<void> {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) {
+    notifyAgent(session, 'add_mcp_server failed: agent group not found.');
+    return;
+  }
+  const serverName = content.name as string;
+  const command = content.command as string;
+  if (!serverName || !command) {
+    notifyAgent(session, 'add_mcp_server failed: name and command are required.');
+    return;
+  }
+  await requestApproval({
+    session,
+    agentName: agentGroup.name,
+    action: 'add_mcp_server',
+    payload: {
+      name: serverName,
+      command,
+      args: (content.args as string[]) || [],
+      env: (content.env as Record<string, string>) || {},
+    },
+    title: 'Add MCP Request',
+    question: `Agent "${agentGroup.name}" is attempting to add a new MCP server:\n${serverName} (${command})`,
+  });
+}

package/src/modules/typing/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Typing indicator refresh — default module.
+ *
+ * Most platforms expire a typing indicator after 5–10s, so a one-shot
+ * call on message arrival goes stale long before the agent finishes
+ * thinking. This module keeps it alive by re-firing `setTyping` on a
+ * short interval — but only while the agent is actually WORKING, gated
+ * on the heartbeat file's mtime after an initial grace period.
+ *
+ * After delivering a user-facing message, the refresh is paused for
+ * POST_DELIVERY_PAUSE_MS so the client-side indicator can visually
+ * clear.
+ *
+ * Default module status:
+ *   - Lives in src/modules/ for signaling (not really core), but ships
+ *     on main and is imported directly by core. No registry, no hook.
+ *   - Removing requires editing src/router.ts, src/delivery.ts, and
+ *     src/container-runner.ts to drop the calls.
+ */
+import fs from 'fs';
+
+import { heartbeatPath } from '../../session-manager.js';
+
+const TYPING_REFRESH_MS = 4000;
+/**
+ * Grace window from startTypingRefresh: fire typing unconditionally
+ * for this long regardless of heartbeat state. Covers container
+ * spawn/wake latency (5–12s on cold start before first heartbeat).
+ */
+const TYPING_GRACE_MS = 15000;
+/**
+ * After the grace window, a heartbeat must be mtimed within this
+ * many ms of now to count as "agent is working." Heartbeats land
+ * every few hundred ms during active work, so 6s is well above
+ * the working floor and small enough to stop typing quickly when
+ * the agent goes idle.
+ */
+const HEARTBEAT_FRESH_MS = 6000;
+/**
+ * After we deliver a user-facing message, pause typing for this
+ * long so the client-side indicator has time to visually clear.
+ * Tuned for the longest common expiry (Discord ~10s). The interval
+ * stays running; ticks inside the pause just skip the setTyping call.
+ */
+const POST_DELIVERY_PAUSE_MS = 10000;
+
+interface TypingAdapter {
+  setTyping?(channelType: string, platformId: string, threadId: string | null): Promise<void>;
+}
+
+interface TypingTarget {
+  agentGroupId: string;
+  channelType: string;
+  platformId: string;
+  threadId: string | null;
+  interval: NodeJS.Timeout;
+  startedAt: number;
+  pausedUntil: number; // epoch ms; 0 = not paused
+}
+
+let adapter: TypingAdapter | null = null;
+const typingRefreshers = new Map<string, TypingTarget>();
+
+/**
+ * Bind the typing module to the channel delivery adapter so it can
+ * call `setTyping`. Called once by `src/delivery.ts` inside
+ * `setDeliveryAdapter`. Passing a fresh adapter replaces the prior
+ * binding and leaves active refreshers in place (they'll use the
+ * new adapter on their next tick).
+ */
+export function setTypingAdapter(a: TypingAdapter): void {
+  adapter = a;
+}
+
+async function triggerTyping(channelType: string, platformId: string, threadId: string | null): Promise<void> {
+  try {
+    await adapter?.setTyping?.(channelType, platformId, threadId);
+  } catch {
+    // Typing is best-effort — don't let it fail delivery or routing.
+  }
+}
+
+function isHeartbeatFresh(agentGroupId: string, sessionId: string): boolean {
+  const hbPath = heartbeatPath(agentGroupId, sessionId);
+  try {
+    const stat = fs.statSync(hbPath);
+    return Date.now() - stat.mtimeMs < HEARTBEAT_FRESH_MS;
+  } catch {
+    return false;
+  }
+}
+
+export function startTypingRefresh(
+  sessionId: string,
+  agentGroupId: string,
+  channelType: string,
+  platformId: string,
+  threadId: string | null,
+): void {
+  const existing = typingRefreshers.get(sessionId);
+  if (existing) {
+    // Already refreshing. Fire an immediate tick for the new inbound
+    // event and reset the grace window — the new message restarts
+    // the container-wake latency budget. Also clear any lingering
+    // post-delivery pause: a new inbound means the user expects
+    // typing to show immediately.
+    triggerTyping(channelType, platformId, threadId).catch(() => {});
+    existing.startedAt = Date.now();
+    existing.pausedUntil = 0;
+    return;
+  }
+
+  // Immediate tick + periodic refresh.
+  triggerTyping(channelType, platformId, threadId).catch(() => {});
+  const startedAt = Date.now();
+  const interval = setInterval(() => {
+    const entry = typingRefreshers.get(sessionId);
+    if (!entry) return; // stopped externally since this tick was scheduled
+
+    // Inside a post-delivery pause: skip setTyping but keep the
+    // interval running so we resume automatically once the pause
+    // expires.
+    if (entry.pausedUntil > Date.now()) return;
+
+    const withinGrace = Date.now() - entry.startedAt < TYPING_GRACE_MS;
+    if (withinGrace || isHeartbeatFresh(entry.agentGroupId, sessionId)) {
+      triggerTyping(entry.channelType, entry.platformId, entry.threadId).catch(() => {});
+      return;
+    }
+
+    // Out of grace AND heartbeat stale — agent is idle, stop refreshing.
+    clearInterval(entry.interval);
+    typingRefreshers.delete(sessionId);
+  }, TYPING_REFRESH_MS);
+  // unref so a stale refresher can't hold the event loop alive.
+  interval.unref();
+  typingRefreshers.set(sessionId, {
+    agentGroupId,
+    channelType,
+    platformId,
+    threadId,
+    interval,
+    startedAt,
+    pausedUntil: 0,
+  });
+}
+
+/**
+ * Pause the typing refresh for POST_DELIVERY_PAUSE_MS. Called after
+ * a user-facing message is delivered so the client-side indicator
+ * has a chance to visually clear before the agent's next SDK event
+ * pushes it back on. No-op if no refresh is active for this session.
+ */
+export function pauseTypingRefreshAfterDelivery(sessionId: string): void {
+  const entry = typingRefreshers.get(sessionId);
+  if (!entry) return;
+  entry.pausedUntil = Date.now() + POST_DELIVERY_PAUSE_MS;
+}
+
+export function stopTypingRefresh(sessionId: string): void {
+  const entry = typingRefreshers.get(sessionId);
+  if (!entry) return;
+  clearInterval(entry.interval);
+  typingRefreshers.delete(sessionId);
+}

package/src/oauth/agent-app-connections.ts

@@ -0,0 +1,103 @@
+/**
+ * Per-agent allowlist for OAuth connections — the `agent_app_connections`
+ * join table. A connection is only visible/injectable to an agent group
+ * if there's a row joining the two.
+ */
+import { getDb } from '../db/connection.js';
+import type { Database } from '../db/connection.js';
+
+function db(): Database {
+  return getDb();
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export interface AgentForConnection {
+  agent_group_id: string;
+  agent_group_folder: string;
+  agent_group_name: string;
+  created_at: string;
+}
+
+export function listAgentsForConnection(connectionId: string): AgentForConnection[] {
+  return db()
+    .prepare<AgentForConnection>(
+      `SELECT a.agent_group_id   AS agent_group_id,
+              g.folder           AS agent_group_folder,
+              g.name             AS agent_group_name,
+              a.created_at       AS created_at
+         FROM agent_app_connections a
+         JOIN agent_groups g ON g.id = a.agent_group_id
+        WHERE a.app_connection_id = @connection_id
+        ORDER BY g.name`,
+    )
+    .all({ connection_id: connectionId });
+}
+
+/** Map of connectionId → agent count, populated in one query for the list view. */
+export function countAgentsByConnection(): Map<string, number> {
+  const rows = db()
+    .prepare<{ app_connection_id: string; n: number }>(
+      `SELECT app_connection_id, COUNT(*) AS n
+         FROM agent_app_connections
+         GROUP BY app_connection_id`,
+    )
+    .all();
+  const out = new Map<string, number>();
+  for (const r of rows) out.set(r.app_connection_id, r.n);
+  return out;
+}
+
+export function listConnectionsForAgent(agentGroupId: string): string[] {
+  return db()
+    .prepare<{ app_connection_id: string }>(
+      `SELECT app_connection_id FROM agent_app_connections WHERE agent_group_id = @agent_group_id`,
+    )
+    .all({ agent_group_id: agentGroupId })
+    .map((r) => r.app_connection_id);
+}
+
+/** Atomically replace the allowlist for a connection. */
+export function setAgentsForConnection(connectionId: string, agentGroupIds: string[]): void {
+  const tx = db().transaction((ids: string[]) => {
+    db()
+      .prepare(`DELETE FROM agent_app_connections WHERE app_connection_id = @connection_id`)
+      .run({ connection_id: connectionId });
+    const insert = db().prepare(
+      `INSERT OR IGNORE INTO agent_app_connections
+         (agent_group_id, app_connection_id, created_at)
+       VALUES (@agent_group_id, @app_connection_id, @created_at)`,
+    );
+    const now = nowIso();
+    for (const id of ids) {
+      insert.run({ agent_group_id: id, app_connection_id: connectionId, created_at: now });
+    }
+  });
+  tx(agentGroupIds);
+}
+
+export function addAgentToConnection(connectionId: string, agentGroupId: string): void {
+  db()
+    .prepare(
+      `INSERT OR IGNORE INTO agent_app_connections
+         (agent_group_id, app_connection_id, created_at)
+       VALUES (@agent_group_id, @app_connection_id, @created_at)`,
+    )
+    .run({
+      agent_group_id: agentGroupId,
+      app_connection_id: connectionId,
+      created_at: nowIso(),
+    });
+}
+
+export function removeAgentFromConnection(connectionId: string, agentGroupId: string): boolean {
+  const r = db()
+    .prepare(
+      `DELETE FROM agent_app_connections
+        WHERE app_connection_id = @connection_id AND agent_group_id = @agent_group_id`,
+    )
+    .run({ connection_id: connectionId, agent_group_id: agentGroupId });
+  return r.changes > 0;
+}

package/src/oauth/app-configs.test.ts

@@ -0,0 +1,64 @@
+import crypto from 'crypto';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { closeDb, initTestDb, runMigrations } from '../db/index.js';
+import { _setMasterKeyForTest } from '../secrets/master-key.js';
+import { deleteAppConfig, getAppConfig, getAppConfigWithSecret, listAppConfigs, putAppConfig } from './app-configs.js';
+
+beforeEach(() => {
+  const db = initTestDb();
+  runMigrations(db);
+  _setMasterKeyForTest(crypto.randomBytes(32));
+});
+
+afterEach(() => closeDb());
+
+describe('app_configs DB layer', () => {
+  it('inserts a config and returns its id', () => {
+    const id = putAppConfig('google', {
+      client_id: 'abc.apps.googleusercontent.com',
+      client_secret: 'super-secret',
+      scopes_default: 'openid email',
+    });
+    expect(id).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it('round-trips client_secret via getAppConfigWithSecret', () => {
+    putAppConfig('google', {
+      client_id: 'abc',
+      client_secret: 'shhh',
+    });
+    const got = getAppConfigWithSecret('google');
+    expect(got?.client_secret).toBe('shhh');
+    expect(got?.client_id).toBe('abc');
+  });
+
+  it('hides client_secret from public reads', () => {
+    putAppConfig('google', { client_id: 'abc', client_secret: 'shhh' });
+    const row = getAppConfig('google') as Record<string, unknown> | undefined;
+    expect(row).toBeDefined();
+    expect(row).not.toHaveProperty('client_secret');
+    expect(row).not.toHaveProperty('client_secret_encrypted');
+  });
+
+  it('updates an existing provider in place', () => {
+    const id1 = putAppConfig('google', { client_id: 'v1', client_secret: 's1' });
+    const id2 = putAppConfig('google', { client_id: 'v2', client_secret: 's2' });
+    expect(id1).toBe(id2);
+    expect(getAppConfig('google')?.client_id).toBe('v2');
+    expect(getAppConfigWithSecret('google')?.client_secret).toBe('s2');
+  });
+
+  it('lists configs alphabetically by provider', () => {
+    putAppConfig('zeta', { client_id: 'z', client_secret: 'sz' });
+    putAppConfig('alpha', { client_id: 'a', client_secret: 'sa' });
+    expect(listAppConfigs().map((r) => r.provider)).toEqual(['alpha', 'zeta']);
+  });
+
+  it('deletes by provider', () => {
+    putAppConfig('google', { client_id: 'abc', client_secret: 'shhh' });
+    expect(deleteAppConfig('google')).toBe(true);
+    expect(getAppConfig('google')).toBeUndefined();
+    expect(deleteAppConfig('google')).toBe(false);
+  });
+});