@openparachute/agent 0.1.2 → 0.2.0

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

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

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

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

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

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

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

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