@openparachute/agent 0.1.0

package/src/modules/approvals/primitive.ts

@@ -0,0 +1,279 @@
+/**
+ * Approvals primitive — the public API that other modules call.
+ *
+ * Two surfaces:
+ *   - `requestApproval()` — queue an approval request, deliver the card to
+ *     the right admin DM, record the row in `approvals` (paraclaw#11). Used
+ *     by any module that needs admin confirmation before doing something
+ *     sensitive.
+ *   - `registerApprovalHandler(action, handler)` — called at module import
+ *     time. When the admin approves a pending row with matching `action`,
+ *     the response handler dispatches into the registered callback. Optional
+ *     modules (self-mod, future module gates) register here.
+ *
+ * Approver picking lives here too — it used to sit in src/access.ts and got
+ * folded in with the PR #7 re-tier. The picks functions walk user_roles
+ * (owner, global admin, scoped admin) and resolve to a reachable DM via the
+ * permissions module's user-dm helper.
+ *
+ * Tier: default module. Permissions is an optional module, so importing from
+ * it here is technically a tier inversion — but the host bundles both with
+ * main, and the alternative (a third "permissions-primitive" default module
+ * exposing just user-roles/user-dms) is more churn than it's worth. Revisit
+ * if either module becomes genuinely optional (see REFACTOR_PLAN open q #3).
+ */
+import { normalizeOptions, type RawOption } from '../../channels/ask-question.js';
+import { getMessagingGroup } from '../../db/messaging-groups.js';
+import { createApproval, getSession } from '../../db/sessions.js';
+import { getDeliveryAdapter } from '../../delivery.js';
+import { wakeContainer } from '../../container-runner.js';
+import { log } from '../../log.js';
+import { decodePlatformIdAs } from '../../platform-id.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import type { MessagingGroup, Session } from '../../types.js';
+import { getAdminsOfAgentGroup, getGlobalAdmins, getOwners } from '../permissions/db/user-roles.js';
+import { ensureUserDm } from '../permissions/user-dm.js';
+
+/** Two-button approval UI — the only options the primitive supports today. */
+const APPROVAL_OPTIONS: RawOption[] = [
+  { label: 'Approve', selectedLabel: '✅ Approved', value: 'approve' },
+  { label: 'Reject', selectedLabel: '❌ Rejected', value: 'reject' },
+];
+
+// ── Approval handler registry ──
+// Modules that want to be called back when an admin approves a pending row
+// register here at import time, keyed by the `action` string they used in
+// their `requestApproval()` calls.
+
+export interface ApprovalHandlerContext {
+  session: Session;
+  payload: Record<string, unknown>;
+  /** User ID of the admin who approved. Empty string if unknown. */
+  userId: string;
+  /** Send a system chat message to the requesting agent's session. */
+  notify: (text: string) => void;
+}
+
+export type ApprovalHandler = (ctx: ApprovalHandlerContext) => Promise<void>;
+
+const approvalHandlers = new Map<string, ApprovalHandler>();
+
+export function registerApprovalHandler(action: string, handler: ApprovalHandler): void {
+  if (approvalHandlers.has(action)) {
+    log.warn('Approval handler re-registered (overwriting)', { action });
+  }
+  approvalHandlers.set(action, handler);
+}
+
+export function getApprovalHandler(action: string): ApprovalHandler | undefined {
+  return approvalHandlers.get(action);
+}
+
+// ── Approver picking ──
+
+/**
+ * Ordered list of user IDs eligible to approve an action for the given agent
+ * group. Preference: admins @ that group → global admins → owners.
+ */
+export function pickApprover(agentGroupId: string | null): string[] {
+  const approvers: string[] = [];
+  const seen = new Set<string>();
+  const add = (id: string): void => {
+    if (!seen.has(id)) {
+      seen.add(id);
+      approvers.push(id);
+    }
+  };
+
+  if (agentGroupId) {
+    for (const r of getAdminsOfAgentGroup(agentGroupId)) add(r.user_id);
+  }
+  for (const r of getGlobalAdmins()) add(r.user_id);
+  for (const r of getOwners()) add(r.user_id);
+
+  return approvers;
+}
+
+/**
+ * Walk the approver list and return the first reachable
+ * (approverId, messagingGroup, viaFallbackBot) tuple. Returns null if
+ * nobody is reachable.
+ *
+ * Resolution order, when both `originChannelType` and `originBotId` are set:
+ *
+ *   1. Same-channel approver, exact `(channel, originBotId)` match —
+ *      best case, the card delivers via the same bot the inbound
+ *      came in on.
+ *   2. Same-channel approver, channel-default DM (`bot_id = ''` slot
+ *      in `user_dms`, configured via `/agent/settings/approvals`) —
+ *      `viaFallbackBot: true`, so callers can name the origin bot in
+ *      the card body to avoid confusion.
+ *   3. Cross-channel approver, channel-default DM — same-channel
+ *      delivery wasn't possible at all (no approver on this channel,
+ *      or none of them have any DM cached).
+ *   4. None — null.
+ *
+ * When only `originChannelType` is provided (single-bot install,
+ * legacy callers), step 1 collapses into step 2: the bot id is
+ * effectively `''` and the channel-default row is the cache.
+ *
+ * Cold-resolve at step 1 hits the adapter registered for
+ * `(channel, originBotId)` directly — see `ensureUserDm` — so a
+ * cache miss for an active secondary bot triggers `openDM` on that
+ * bot, not on whichever bot happens to be first in the registry.
+ */
+export async function pickApprovalDelivery(
+  approvers: string[],
+  originChannelType: string,
+  originBotId: string | null = null,
+): Promise<{ userId: string; messagingGroup: MessagingGroup; viaFallbackBot: boolean } | null> {
+  // Step 1 — same channel, exact bot match.
+  if (originChannelType && originBotId) {
+    for (const userId of approvers) {
+      if (channelTypeOf(userId) !== originChannelType) continue;
+      const mg = await ensureUserDm(userId, { botId: originBotId });
+      if (mg) return { userId, messagingGroup: mg, viaFallbackBot: false };
+    }
+  }
+  // Step 2 — same channel, channel-default DM. `viaFallbackBot` is true
+  // only when an originBotId was requested but didn't resolve.
+  if (originChannelType) {
+    for (const userId of approvers) {
+      if (channelTypeOf(userId) !== originChannelType) continue;
+      const mg = await ensureUserDm(userId);
+      if (mg) return { userId, messagingGroup: mg, viaFallbackBot: !!originBotId };
+    }
+  }
+  // Step 3 — cross-channel any.
+  for (const userId of approvers) {
+    const mg = await ensureUserDm(userId);
+    if (mg) return { userId, messagingGroup: mg, viaFallbackBot: !!originBotId };
+  }
+  return null;
+}
+
+function channelTypeOf(userId: string): string {
+  const idx = userId.indexOf(':');
+  return idx < 0 ? '' : userId.slice(0, idx);
+}
+
+// ── Request API ──
+
+/** Send a system chat to the agent's session. Used by callers and by the response handler. */
+export function notifyAgent(session: Session, text: string): void {
+  writeSessionMessage(session.agent_group_id, session.id, {
+    id: `sys-${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, sender: 'system', senderId: 'system' }),
+  });
+  const fresh = getSession(session.id);
+  if (fresh) {
+    wakeContainer(fresh).catch((err) => log.error('Failed to wake container after notification', { err }));
+  }
+}
+
+export interface RequestApprovalOptions {
+  session: Session;
+  agentName: string;
+  /** Free-form action identifier. Must match the key the consumer registered via registerApprovalHandler. */
+  action: string;
+  /** JSON-serializable opaque payload. Carried in the approvals row body, handed to the handler on approve. */
+  payload: Record<string, unknown>;
+  /** Card title shown to the admin. */
+  title: string;
+  /** Card body shown to the admin. */
+  question: string;
+}
+
+/**
+ * Queue an approval request. Picks an approver, delivers the card to their
+ * DM, and records the row in `approvals` (kind = action). Fire-and-forget
+ * from the caller's perspective — the admin's response kicks off the
+ * registered approval handler for this action via the response dispatcher.
+ */
+export async function requestApproval(opts: RequestApprovalOptions): Promise<void> {
+  const { session, action, payload, title, question, agentName } = opts;
+
+  const approvers = pickApprover(session.agent_group_id);
+  if (approvers.length === 0) {
+    notifyAgent(session, `${action} failed: no owner or admin configured to approve.`);
+    return;
+  }
+
+  const originMg = session.messaging_group_id ? (getMessagingGroup(session.messaging_group_id) ?? null) : null;
+  const originChannelType = originMg?.channel_type ?? '';
+  // The session's MG is paraclaw-managed and gets v2-shaped on creation
+  // (or backfilled by startup-bootstrap), so slot1 of the platform_id is
+  // the bot id. v1 rows return botId=null and we route by channel only —
+  // same path as a single-bot install.
+  const originBotId = originMg ? decodePlatformIdAs(originMg.platform_id, 'v2').botId : null;
+
+  const target = await pickApprovalDelivery(approvers, originChannelType, originBotId);
+  if (!target) {
+    const hint = originBotId ? ` Ask them to DM ${originBotId} once so the bot can reach them, then retry.` : '';
+    notifyAgent(session, `${action} failed: no DM channel found for any eligible approver.${hint}`);
+    return;
+  }
+
+  const approvalId = `appr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const normalizedOptions = normalizeOptions(APPROVAL_OPTIONS);
+  createApproval({
+    id: approvalId,
+    kind: action,
+    agent_group_id: session.agent_group_id,
+    session_id: session.id,
+    body: {
+      title,
+      options: normalizedOptions,
+      request_id: approvalId,
+      payload,
+      platform_id: target.messagingGroup.platform_id,
+      channel_type: target.messagingGroup.channel_type,
+      thread_id: null,
+      platform_message_id: null,
+    },
+    created_at: new Date().toISOString(),
+  });
+
+  const adapter = getDeliveryAdapter();
+  if (adapter) {
+    try {
+      await adapter.deliver(
+        target.messagingGroup.channel_type,
+        target.messagingGroup.platform_id,
+        null,
+        'chat-sdk',
+        JSON.stringify({
+          type: 'ask_question',
+          questionId: approvalId,
+          title,
+          question: appendFallbackNotice(question, target.viaFallbackBot, originBotId),
+          options: APPROVAL_OPTIONS,
+        }),
+      );
+    } catch (err) {
+      log.error('Failed to deliver approval card', { action, approvalId, err });
+      notifyAgent(session, `${action} failed: could not deliver approval request to ${target.userId}.`);
+      return;
+    }
+  }
+
+  log.info('Approval requested', { action, approvalId, agentName, approver: target.userId });
+}
+
+/**
+ * When `pickApprovalDelivery` falls back to the channel-default bot
+ * (because the inbound bot can't DM this approver), append a one-line
+ * notice to the card body. Surfaces the mismatch at the moment the
+ * approver is making a decision, with a pointer to where they can
+ * change the default if they want cards on the originating bot.
+ */
+export function appendFallbackNotice(question: string, viaFallbackBot: boolean, originBotId: string | null): string {
+  if (!viaFallbackBot) return question;
+  const hint = originBotId ? ` (inbound bot ${originBotId})` : '';
+  return `${question}\n\n_Routed via your default approval bot${hint}. Change in /agent/settings/approvals._`;
+}

package/src/modules/approvals/project.md

@@ -0,0 +1,27 @@
+## Approvals module
+
+Admin-gated approval flow for agent self-modification. Lives in `src/modules/approvals/`.
+
+### Flow
+
+The container writes a `system`-kind outbound row with one of two actions — `install_packages`, `add_mcp_server`. The module's delivery-action handlers validate, route to the right approver's DM, and persist a `pending_approvals` row. When the admin clicks a button, the registered response handler applies the change (config update → image rebuild if needed → container kill) and notifies the agent via system chat.
+
+### Wiring
+
+- **Delivery actions:** `install_packages`, `add_mcp_server` via `registerDeliveryAction`.
+- **Response handler:** claims approval cards by `pending_approvals` row lookup.
+
+### Tables
+
+`pending_approvals` (created by `module-approvals-pending-approvals.ts`). Not dropped on uninstall — approvals in flight aren't lost on reinstall.
+
+### Core integration
+
+The module depends on host-side infra but does not reach into core decision paths beyond the registered hooks:
+
+- `buildAgentGroupImage`, `killContainer` from container-runner (image rebuilds)
+- `updateContainerConfig` from container-config (apt/npm/mcp edits)
+- `pickApprover`, `pickApprovalDelivery` from access
+- `getDeliveryAdapter` in request-approval.ts
+
+No core code imports from this module. Removing it: delete `src/modules/approvals/`, remove the import from `src/modules/index.ts`. Delivery actions will log "Unknown system action"; button clicks on approval cards will log "Unclaimed response". Stale rows remain in `pending_approvals` until reinstall or manual cleanup.

package/src/modules/approvals/response-handler.ts

@@ -0,0 +1,87 @@
+/**
+ * Handle an admin's response to an approval card.
+ *
+ * Module-initiated actions — the module called `requestApproval()` with some
+ * free-form `action` string and registered a handler via
+ * `registerApprovalHandler(action, handler)`. On approve, we look up the
+ * handler and call it; on reject, we notify the agent and move on.
+ *
+ * The response handler is registered via core's `registerResponseHandler`;
+ * core iterates handlers and the first one to return `true` claims the response.
+ */
+import { wakeContainer } from '../../container-runner.js';
+import { deleteApproval, getApproval, getSession } from '../../db/sessions.js';
+import type { ResponsePayload } from '../../response-registry.js';
+import { log } from '../../log.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import type { ActionApprovalBody, Approval } from '../../types.js';
+import { getApprovalHandler } from './primitive.js';
+
+export async function handleApprovalsResponse(payload: ResponsePayload): Promise<boolean> {
+  const approval = getApproval(payload.questionId);
+  if (!approval) return false;
+  if (approval.kind === 'question') return false;
+
+  await handleRegisteredApproval(approval, payload.value, payload.userId ?? '');
+  return true;
+}
+
+async function handleRegisteredApproval(approval: Approval, selectedOption: string, userId: string): Promise<void> {
+  if (!approval.session_id) {
+    deleteApproval(approval.id);
+    return;
+  }
+  const session = getSession(approval.session_id);
+  if (!session) {
+    deleteApproval(approval.id);
+    return;
+  }
+
+  const notify = (text: string): void => {
+    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, sender: 'system', senderId: 'system' }),
+    });
+  };
+
+  if (selectedOption !== 'approve') {
+    notify(`Your ${approval.kind} request was rejected by admin.`);
+    log.info('Approval rejected', { approvalId: approval.id, action: approval.kind, userId });
+    deleteApproval(approval.id);
+    await wakeContainer(session);
+    return;
+  }
+
+  // Approved — dispatch to the module that registered for this action.
+  const handler = getApprovalHandler(approval.kind);
+  if (!handler) {
+    log.warn('No approval handler registered — row dropped', {
+      approvalId: approval.id,
+      action: approval.kind,
+    });
+    notify(`Your ${approval.kind} was approved, but no handler is installed to apply it.`);
+    deleteApproval(approval.id);
+    await wakeContainer(session);
+    return;
+  }
+
+  const body = approval.body as ActionApprovalBody;
+  const payload = body.payload ?? {};
+  try {
+    await handler({ session, payload, userId, notify });
+    log.info('Approval handled', { approvalId: approval.id, action: approval.kind, userId });
+  } catch (err) {
+    log.error('Approval handler threw', { approvalId: approval.id, action: approval.kind, err });
+    notify(
+      `Your ${approval.kind} was approved, but applying it failed: ${err instanceof Error ? err.message : String(err)}.`,
+    );
+  }
+
+  deleteApproval(approval.id);
+  await wakeContainer(session);
+}

package/src/modules/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Modules barrel.
+ *
+ * Each module self-registers at import time. This barrel is imported by
+ * src/index.ts for side effects (registry registrations, typing impl setup,
+ * etc.). Core runs with an empty barrel — the registries have inline
+ * fallbacks and `sqlite_master` guards.
+ *
+ * Default modules (ship with main, direct core import):
+ *   - src/modules/typing/        → imported directly by router/delivery/container-runner
+ *   - src/modules/mount-security/ → imported directly by container-runner
+ *
+ * Registry-based modules (installed via /add-<name> skills, pulled from the
+ * `modules` branch): append imports below.
+ */
+// Approvals (default tier) must load before self-mod (optional) so the
+// registerApprovalHandler / requestApproval symbols are bound when self-mod
+// registers its handlers at import time.
+import './approvals/index.js';
+import './interactive/index.js';
+import './scheduling/index.js';
+import './permissions/index.js';
+import './agent-to-agent/index.js';
+import './self-mod/index.js';

package/src/modules/interactive/agent.md

@@ -0,0 +1,21 @@
+## ask_user_question
+
+Use `ask_user_question` when you need the user to pick from a small set of concrete options and you can't infer a reasonable default. This is a **blocking** call — your turn pauses until the user clicks or the timeout expires.
+
+**When to use:**
+- Confirming a destructive action ("Delete these 3 files?")
+- Choosing between incompatible paths ("Keep their version or yours?")
+- Gathering a required parameter that must be one of a known set
+
+**When NOT to use:**
+- Open-ended text input — just send a regular message asking.
+- Yes/no confirmations where "no" is the safe default — just proceed and let the user interrupt.
+- Anything you can work out from context.
+
+**Arguments:**
+- `title` (string) — short card header, e.g. "Confirm deletion"
+- `question` (string) — the full question
+- `options` (array) — each is either a plain string or `{ label, selectedLabel?, value? }`. `selectedLabel` replaces the button text after click; `value` is what gets returned to you
+- `timeout` (number, seconds, default 300) — how long to wait before giving up
+
+The response is the `value` (or label if no value set) of whichever option the user chose. On timeout you get an error and should proceed with a sensible default or tell the user you timed out.

package/src/modules/interactive/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Interactive module — generic ask_user_question flow.
+ *
+ * Container-side `ask_user_question` writes a chat-sdk card to outbound.db +
+ * polls inbound.db for a `question_response` system message. On the host side
+ * this module handles the button-click response: look up the `approvals` row
+ * (kind='question'), write the response into the session's inbound.db, wake
+ * the container.
+ *
+ * The `createApproval` call in `deliverMessage` (delivery.ts) stays inline in
+ * core — it's 15 lines guarded by `hasTable('approvals')`, modularizing it
+ * adds more registry surface than it saves.
+ */
+import { getDb, hasTable } from '../../db/connection.js';
+import { deleteApproval, getApproval, getSession } from '../../db/sessions.js';
+import { wakeContainer } from '../../container-runner.js';
+import { registerResponseHandler, type ResponsePayload } from '../../response-registry.js';
+import { log } from '../../log.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import type { QuestionApprovalBody } from '../../types.js';
+
+async function handleInteractiveResponse(payload: ResponsePayload): Promise<boolean> {
+  if (!hasTable(getDb(), 'approvals')) return false;
+
+  const approval = getApproval(payload.questionId);
+  if (!approval || approval.kind !== 'question') return false;
+
+  if (!approval.session_id) {
+    deleteApproval(payload.questionId);
+    return true;
+  }
+  const session = getSession(approval.session_id);
+  if (!session) {
+    log.warn('Session not found for pending question', {
+      questionId: payload.questionId,
+      sessionId: approval.session_id,
+    });
+    deleteApproval(payload.questionId);
+    return true; // claimed — we owned this questionId even though the session is gone
+  }
+
+  const body = approval.body as QuestionApprovalBody;
+  writeSessionMessage(session.agent_group_id, session.id, {
+    id: `qr-${payload.questionId}-${Date.now()}`,
+    kind: 'system',
+    timestamp: new Date().toISOString(),
+    platformId: body.platform_id,
+    channelType: body.channel_type,
+    threadId: body.thread_id,
+    content: JSON.stringify({
+      type: 'question_response',
+      questionId: payload.questionId,
+      selectedOption: payload.value,
+      userId: payload.userId ?? '',
+    }),
+  });
+
+  deleteApproval(payload.questionId);
+  log.info('Question response routed', {
+    questionId: payload.questionId,
+    selectedOption: payload.value,
+    sessionId: session.id,
+  });
+
+  await wakeContainer(session);
+  return true;
+}
+
+registerResponseHandler(handleInteractiveResponse);

package/src/modules/interactive/project.md

@@ -0,0 +1,12 @@
+## Interactive module
+
+Generic ask_user_question flow. Lives in `src/modules/interactive/`.
+
+The container-side MCP tool `ask_user_question` writes a chat-sdk card to outbound.db and polls inbound.db for a `question_response` system message. The host side of this is split:
+
+- **Inline in `src/delivery.ts`:** the `deliverMessage` path intercepts `content.type === 'ask_question'` messages and writes a row to the unified `approvals` table with `kind='question'`. Guarded by `hasTable(db, 'approvals')`.
+- **This module:** registers a `ResponseHandler` that runs when a button-click arrives via the channel adapter's `onAction`. It looks up the `approvals` row (filtered to `kind='question'`), writes a `question_response` system message into the session's inbound.db, wakes the container.
+
+The `approvals` table is created by migration 024 (paraclaw#11), which collapsed the previous `pending_questions` and `pending_approvals` tables into one. The module doesn't own the schema, just the behavior. Removing the module disables the button-click response path for questions only; admin approvals (other kinds) still flow through `src/modules/approvals/`, and cards are still delivered.
+
+`getAskQuestionRender` in `src/db/sessions.ts` resolves card render metadata for `chat-sdk-bridge.ts`. It reads from `approvals` and from the permissions module's side tables (`pending_channel_approvals`, `pending_sender_approvals`), degrading via `hasTable`. Stays in core.