@openparachute/agent 0.1.1 → 0.2.0

package/src/modules/approvals/primitive.ts

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

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

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

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

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

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

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