@openparachute/agent 0.1.0

package/src/command-gate.ts

@@ -0,0 +1,63 @@
+/**
+ * Host-side command gate. Classifies inbound slash commands and gates
+ * them before they reach the container.
+ *
+ * - Filtered commands: dropped silently (never reach the container)
+ * - Admin commands: checked against user_roles; denied senders get a
+ *   "Permission denied" response written directly to messages_out
+ * - Normal messages: pass through unchanged
+ */
+import { getDb, hasTable } from './db/connection.js';
+
+export type GateResult = { action: 'pass' } | { action: 'filter' } | { action: 'deny'; command: string };
+
+const FILTERED_COMMANDS = new Set(['/help', '/login', '/logout', '/doctor', '/config', '/remote-control']);
+const ADMIN_COMMANDS = new Set(['/clear', '/compact', '/context', '/cost', '/files']);
+
+/**
+ * Classify a message and decide whether it should reach the container.
+ * Returns 'pass' for normal messages and authorized admin commands,
+ * 'filter' for silently-dropped commands, 'deny' for unauthorized
+ * admin commands.
+ */
+export function gateCommand(content: string, userId: string | null, agentGroupId: string): GateResult {
+  let text: string;
+  try {
+    const parsed = JSON.parse(content);
+    text = (parsed.text || '').trim();
+  } catch {
+    text = content.trim();
+  }
+
+  if (!text.startsWith('/')) return { action: 'pass' };
+
+  const command = text.split(/\s/)[0].toLowerCase();
+
+  if (FILTERED_COMMANDS.has(command)) return { action: 'filter' };
+
+  if (ADMIN_COMMANDS.has(command)) {
+    if (isAdmin(userId, agentGroupId)) {
+      return { action: 'pass' };
+    }
+    return { action: 'deny', command };
+  }
+
+  // Unknown slash commands pass through (the agent/SDK handles them)
+  return { action: 'pass' };
+}
+
+function isAdmin(userId: string | null, agentGroupId: string): boolean {
+  if (!userId) return false;
+  if (!hasTable(getDb(), 'user_roles')) return true; // no permissions module = allow all
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT 1 FROM user_roles
+       WHERE user_id = ?
+         AND (role = 'owner' OR role = 'admin')
+         AND (agent_group_id IS NULL OR agent_group_id = ?)
+       LIMIT 1`,
+    )
+    .get(userId, agentGroupId);
+  return row != null;
+}

package/src/config.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Tests for env-var-driven config resolution.
+ *
+ * `vi.resetModules()` is required because config.ts resolves PARACHUTE_DIR
+ * at import time — the const captures whatever PARACHUTE_HOME / HOME are
+ * at first load. Tests that flip env vars must re-import to observe the
+ * new resolution.
+ */
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ORIGINAL_HOME = process.env.HOME;
+const ORIGINAL_PARACHUTE_HOME = process.env.PARACHUTE_HOME;
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+afterEach(() => {
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+  if (ORIGINAL_PARACHUTE_HOME === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = ORIGINAL_PARACHUTE_HOME;
+});
+
+describe('PARACHUTE_DIR resolution', () => {
+  it('PARACHUTE_HOME wins when set', async () => {
+    process.env.PARACHUTE_HOME = '/tmp/sandbox-home';
+    process.env.HOME = '/Users/test';
+    const cfg = await import('./config.js');
+    expect(cfg.PARACHUTE_DIR).toBe('/tmp/sandbox-home');
+    expect(cfg.CENTRAL_DB_DIR).toBe('/tmp/sandbox-home/agent');
+  });
+
+  it('falls back to <HOME>/.parachute when PARACHUTE_HOME unset', async () => {
+    delete process.env.PARACHUTE_HOME;
+    process.env.HOME = '/Users/test';
+    const cfg = await import('./config.js');
+    expect(cfg.PARACHUTE_DIR).toBe(path.join('/Users/test', '.parachute'));
+    expect(cfg.CENTRAL_DB_DIR).toBe(path.join('/Users/test', '.parachute', 'agent'));
+  });
+
+  it('master.key lives next to the central DB under PARACHUTE_DIR/agent', async () => {
+    process.env.PARACHUTE_HOME = '/tmp/sandbox-home-2';
+    const cfg = await import('./config.js');
+    const { getMasterKeyPath } = await import('./secrets/master-key.js');
+    expect(getMasterKeyPath()).toBe(path.join(cfg.CENTRAL_DB_DIR, 'master.key'));
+    expect(getMasterKeyPath().startsWith('/tmp/sandbox-home-2/agent/')).toBe(true);
+  });
+
+  it('PARACHUTE_AGENT_CENTRAL_DB_PATH overrides the DB path independently', async () => {
+    process.env.PARACHUTE_HOME = '/tmp/ignored-for-db-path';
+    process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH = '/tmp/explicit/db.sqlite';
+    const cfg = await import('./config.js');
+    expect(cfg.CENTRAL_DB_PATH).toBe('/tmp/explicit/db.sqlite');
+    delete process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH;
+  });
+
+  it('legacy PARACLAW_CENTRAL_DB_PATH read through 0.1.x compat (drop in 0.2.0)', async () => {
+    process.env.PARACHUTE_HOME = '/tmp/legacy-compat';
+    process.env.PARACLAW_CENTRAL_DB_PATH = '/tmp/legacy/db.sqlite';
+    delete process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH;
+    const cfg = await import('./config.js');
+    expect(cfg.CENTRAL_DB_PATH).toBe('/tmp/legacy/db.sqlite');
+    delete process.env.PARACLAW_CENTRAL_DB_PATH;
+  });
+
+  it('PARACHUTE_AGENT_CENTRAL_DB_PATH takes precedence over legacy PARACLAW_CENTRAL_DB_PATH', async () => {
+    process.env.PARACHUTE_HOME = '/tmp/precedence-check';
+    process.env.PARACLAW_CENTRAL_DB_PATH = '/tmp/legacy/db.sqlite';
+    process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH = '/tmp/current/db.sqlite';
+    const cfg = await import('./config.js');
+    expect(cfg.CENTRAL_DB_PATH).toBe('/tmp/current/db.sqlite');
+    delete process.env.PARACLAW_CENTRAL_DB_PATH;
+    delete process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH;
+  });
+
+  it('PARACHUTE_HOME + PARACHUTE_AGENT_CENTRAL_DB_PATH split: DB takes the override, master.key follows PARACHUTE_HOME', async () => {
+    // Intentional split. PARACHUTE_AGENT_CENTRAL_DB_PATH is an escape hatch
+    // for landing the DB on a different volume (e.g. NVMe scratch) while
+    // keeping the rest of parachute-agent's persistent state — including
+    // the encryption key — under PARACHUTE_HOME. Anyone exporting just the
+    // DB file alone is doing it wrong: the ciphertext is unreadable without
+    // the master key that lives next to PARACHUTE_HOME's agent/ dir.
+    process.env.PARACHUTE_HOME = '/tmp/sandbox-split';
+    process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH = '/var/db/agent.db';
+    const cfg = await import('./config.js');
+    const { getMasterKeyPath } = await import('./secrets/master-key.js');
+    expect(cfg.CENTRAL_DB_PATH).toBe('/var/db/agent.db');
+    expect(getMasterKeyPath()).toBe(path.join('/tmp/sandbox-split/agent', 'master.key'));
+    delete process.env.PARACHUTE_AGENT_CENTRAL_DB_PATH;
+  });
+});

package/src/config.ts

@@ -0,0 +1,108 @@
+import os from 'os';
+import path from 'path';
+
+import { readEnvFile, readEnvWithLegacy } from './env.js';
+import { getContainerImageBase, getDefaultContainerImage, getInstallSlug } from './install-slug.js';
+import { isValidTimezone } from './timezone.js';
+
+// Read config values from .env (falls back to process.env).
+const envConfig = readEnvFile(['ASSISTANT_NAME', 'ASSISTANT_HAS_OWN_NUMBER', 'TZ']);
+
+export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || envConfig.ASSISTANT_NAME || 'Andy';
+export const ASSISTANT_HAS_OWN_NUMBER =
+  (process.env.ASSISTANT_HAS_OWN_NUMBER || envConfig.ASSISTANT_HAS_OWN_NUMBER) === 'true';
+
+// Absolute paths needed for container mounts
+const PROJECT_ROOT = process.cwd();
+const HOME_DIR = process.env.HOME || os.homedir();
+
+// Parachute ecosystem root. Convention shared with parachute-hub, vault,
+// scribe — every module's persistent state lands under this directory
+// (`<PARACHUTE_DIR>/<module>/`). Override via `PARACHUTE_HOME` for sandboxes
+// or Docker. Default: `~/.parachute/`. See docs/sandbox-isolation.md.
+export const PARACHUTE_DIR = process.env.PARACHUTE_HOME || path.join(HOME_DIR, '.parachute');
+
+// Mount security: allowlist stored OUTSIDE project root, never mounted into
+// containers. The directory was renamed paraclaw → parachute-agent in 0.1.0.
+// `migrateLegacyAllowlistDir` (src/modules/mount-security/index.ts) moves any
+// pre-existing files from the legacy dir on first 0.1.0 boot. The legacy
+// constants are exported for the migration to consult; nothing else should
+// read them. Drop in 0.2.0.
+export const ALLOWLIST_DIR = path.join(HOME_DIR, '.config', 'parachute-agent');
+export const LEGACY_ALLOWLIST_DIR = path.join(HOME_DIR, '.config', 'paraclaw');
+export const MOUNT_ALLOWLIST_PATH = path.join(ALLOWLIST_DIR, 'mount-allowlist.json');
+export const SENDER_ALLOWLIST_PATH = path.join(ALLOWLIST_DIR, 'sender-allowlist.json');
+export const STORE_DIR = path.resolve(PROJECT_ROOT, 'store');
+export const GROUPS_DIR = path.resolve(PROJECT_ROOT, 'groups');
+export const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');
+
+// Central DB lives outside the project tree so that:
+//   1. `git clean` / fresh checkouts can never wipe operator-owned state.
+//   2. Multiple project checkouts on the same host share one source of truth.
+//   3. The DB sits next to `master.key` under `<PARACHUTE_DIR>/agent/` so a
+//      single backup of that directory captures both crypto material and DB
+//      state.
+//
+// Two legacy locations exist and are both migrated-on-startup
+// (see `migrateCentralDbLocation` in src/db/connection.ts):
+//   - `<PROJECT_ROOT>/data/v2.db` (pre-0.0.6 in-tree path)
+//   - `<PARACHUTE_DIR>/claw/paraclaw.db` (pre-0.1.0, before the
+//     paraclaw → parachute-agent rename)
+// `PARACHUTE_AGENT_CENTRAL_DB_PATH` is the canonical override; the legacy
+// `PARACLAW_CENTRAL_DB_PATH` name is read for one cycle (0.1.x) with a
+// one-shot warning so operator scripts and `.env` files still resolve.
+// Drop the legacy read in 0.2.0.
+export const CENTRAL_DB_DIR = path.join(PARACHUTE_DIR, 'agent');
+export const CENTRAL_DB_PATH =
+  readEnvWithLegacy('PARACHUTE_AGENT_CENTRAL_DB_PATH', 'PARACLAW_CENTRAL_DB_PATH') ||
+  path.join(CENTRAL_DB_DIR, 'agent.db');
+export const LEGACY_CENTRAL_DB_PATH = path.join(DATA_DIR, 'v2.db');
+export const LEGACY_PARACLAW_DB_DIR = path.join(PARACHUTE_DIR, 'claw');
+export const LEGACY_PARACLAW_DB_PATH = path.join(LEGACY_PARACLAW_DB_DIR, 'paraclaw.db');
+
+// Per-checkout image tag so two installs on the same host don't share
+// `parachute-agent-image:latest` and clobber each other on rebuild.
+export const CONTAINER_IMAGE_BASE = process.env.CONTAINER_IMAGE_BASE || getContainerImageBase(PROJECT_ROOT);
+export const CONTAINER_IMAGE = process.env.CONTAINER_IMAGE || getDefaultContainerImage(PROJECT_ROOT);
+// Install slug — stamped onto every spawned container via --label so
+// cleanupOrphans only reaps containers from this install, not peers.
+export const INSTALL_SLUG = getInstallSlug(PROJECT_ROOT);
+export const CONTAINER_INSTALL_LABEL = `parachute-agent-install=${INSTALL_SLUG}`;
+// Pre-0.1.0 label, before the paraclaw → parachute-agent rename. Kept in the
+// reap query for one cycle so containers spawned by an older host process get
+// cleaned up when this one starts. Drop in 0.2.0 (tracked as a follow-up
+// issue at PR open time).
+export const LEGACY_PARACLAW_INSTALL_LABEL = `paraclaw-install=${INSTALL_SLUG}`;
+export const CONTAINER_TIMEOUT = parseInt(process.env.CONTAINER_TIMEOUT || '1800000', 10);
+export const CONTAINER_MAX_OUTPUT_SIZE = parseInt(process.env.CONTAINER_MAX_OUTPUT_SIZE || '10485760', 10); // 10MB default
+export const MAX_MESSAGES_PER_PROMPT = Math.max(1, parseInt(process.env.MAX_MESSAGES_PER_PROMPT || '10', 10) || 10);
+export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30min default — how long to keep container alive after last result
+export const MAX_CONCURRENT_CONTAINERS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_CONTAINERS || '5', 10) || 5);
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function buildTriggerPattern(trigger: string): RegExp {
+  return new RegExp(`^${escapeRegex(trigger.trim())}\\b`, 'i');
+}
+
+export const DEFAULT_TRIGGER = `@${ASSISTANT_NAME}`;
+
+export function getTriggerPattern(trigger?: string): RegExp {
+  const normalizedTrigger = trigger?.trim();
+  return buildTriggerPattern(normalizedTrigger || DEFAULT_TRIGGER);
+}
+
+export const TRIGGER_PATTERN = buildTriggerPattern(DEFAULT_TRIGGER);
+
+// Timezone for scheduled tasks, message formatting, etc.
+// Validates each candidate is a real IANA identifier before accepting.
+function resolveConfigTimezone(): string {
+  const candidates = [process.env.TZ, envConfig.TZ, Intl.DateTimeFormat().resolvedOptions().timeZone];
+  for (const tz of candidates) {
+    if (tz && isValidTimezone(tz)) return tz;
+  }
+  return 'UTC';
+}
+export const TIMEZONE = resolveConfigTimezone();

package/src/container-config.ts

@@ -0,0 +1,167 @@
+/**
+ * Per-group container config, stored as a plain JSON file at
+ * `groups/<folder>/container.json`. Mounted read-only inside the container
+ * at `/workspace/agent/container.json` — the runner reads it at startup but
+ * cannot modify it. Config changes go through the self-mod approval flow.
+ *
+ * All fields are optional — a missing file or a partial file both resolve
+ * to sensible defaults. Writes are atomic-enough (write-then-rename is not
+ * worth the ceremony here since there's only one writer in practice: the
+ * host, from the delivery thread that processes approved system actions).
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { GROUPS_DIR } from './config.js';
+
+/**
+ * MCP server configuration. Two transports supported (matches Claude Agent
+ * SDK's native `mcpServers` shape — both pass through `sdkQuery({mcpServers})`
+ * unchanged in `container/agent-runner/src/providers/claude.ts`):
+ *
+ *   - **stdio** (the historical default): `command` + optional `args`/`env`,
+ *     spawned in-process by the agent runner.
+ *   - **http**: an HTTP-transport MCP endpoint reachable from the container
+ *     (`url` + optional `headers`). Used by Paraclaw to wire a Parachute
+ *     Vault MCP server in via `Authorization: Bearer pvt_…`.
+ *
+ * The `type` field is optional for back-compat — when absent, presence of
+ * `command` implies stdio. New entries should set `type` explicitly.
+ *
+ * `instructions` is transport-agnostic: when set, the host writes the
+ * content to `.claude-fragments/mcp-<name>.md` at spawn and imports it
+ * into the composed CLAUDE.md.
+ */
+export type McpServerConfig = StdioMcpServerConfig | HttpMcpServerConfig | LegacyMcpServerConfig;
+
+export interface StdioMcpServerConfig {
+  type: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  instructions?: string;
+}
+
+export interface HttpMcpServerConfig {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+  instructions?: string;
+}
+
+/**
+ * Pre-`type` stdio shape. Treated as `{ type: 'stdio', ... }`; kept as its
+ * own variant so existing container.json files (and any legacy code paths
+ * that construct configs without `type`) still type-check.
+ */
+export interface LegacyMcpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  instructions?: string;
+}
+
+export interface AdditionalMountConfig {
+  hostPath: string;
+  containerPath: string;
+  readonly?: boolean;
+}
+
+export interface ContainerConfig {
+  mcpServers: Record<string, McpServerConfig>;
+  packages: { apt: string[]; npm: string[] };
+  imageTag?: string;
+  additionalMounts: AdditionalMountConfig[];
+  /** Which skills to enable — array of skill names or "all" (default). */
+  skills: string[] | 'all';
+  /** Agent provider name (e.g. "claude", "opencode"). Default: "claude". */
+  provider?: string;
+  /** Agent group display name (used in transcript archiving). */
+  groupName?: string;
+  /** Assistant display name (used in system prompt / responses). */
+  assistantName?: string;
+  /** Agent group ID — set by the host, read by the runner. */
+  agentGroupId?: string;
+  /** Max messages per prompt. Falls back to code default if unset. */
+  maxMessagesPerPrompt?: number;
+}
+
+function emptyConfig(): ContainerConfig {
+  return {
+    mcpServers: {},
+    packages: { apt: [], npm: [] },
+    additionalMounts: [],
+    skills: 'all',
+  };
+}
+
+function configPath(folder: string): string {
+  return path.join(GROUPS_DIR, folder, 'container.json');
+}
+
+/**
+ * Read the container config for a group, returning sensible defaults for
+ * any missing fields (or an entirely empty config if the file is absent).
+ * Never throws for missing / malformed files — corruption logs a warning
+ * via console.error and falls back to empty.
+ */
+export function readContainerConfig(folder: string): ContainerConfig {
+  const p = configPath(folder);
+  if (!fs.existsSync(p)) return emptyConfig();
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as Partial<ContainerConfig>;
+    return {
+      mcpServers: raw.mcpServers ?? {},
+      packages: {
+        apt: raw.packages?.apt ?? [],
+        npm: raw.packages?.npm ?? [],
+      },
+      imageTag: raw.imageTag,
+      additionalMounts: raw.additionalMounts ?? [],
+      skills: raw.skills ?? 'all',
+      provider: raw.provider,
+      groupName: raw.groupName,
+      assistantName: raw.assistantName,
+      agentGroupId: raw.agentGroupId,
+      maxMessagesPerPrompt: raw.maxMessagesPerPrompt,
+    };
+  } catch (err) {
+    console.error(`[container-config] failed to parse ${p}: ${String(err)}`);
+    return emptyConfig();
+  }
+}
+
+/**
+ * Write the container config for a group, creating the groups/<folder>/
+ * directory if necessary. Pretty-printed JSON so diffs in the activation
+ * flow are reviewable.
+ */
+export function writeContainerConfig(folder: string, config: ContainerConfig): void {
+  const p = configPath(folder);
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Apply a mutator function to a group's container config and persist the
+ * result. Convenient for append-style changes like `install_packages` and
+ * `add_mcp_server` handlers.
+ */
+export function updateContainerConfig(folder: string, mutate: (config: ContainerConfig) => void): ContainerConfig {
+  const config = readContainerConfig(folder);
+  mutate(config);
+  writeContainerConfig(folder, config);
+  return config;
+}
+
+/**
+ * Initialize an empty container.json for a group if one doesn't already
+ * exist. Idempotent — used from `group-init.ts`.
+ */
+export function initContainerConfig(folder: string): boolean {
+  const p = configPath(folder);
+  if (fs.existsSync(p)) return false;
+  writeContainerConfig(folder, emptyConfig());
+  return true;
+}

package/src/container-runner.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveProviderName } from './container-runner.js';
+
+describe('resolveProviderName', () => {
+  it('prefers session over group and container.json', () => {
+    expect(resolveProviderName('codex', 'opencode', 'claude')).toBe('codex');
+  });
+
+  it('falls back to group when session is null', () => {
+    expect(resolveProviderName(null, 'codex', 'claude')).toBe('codex');
+  });
+
+  it('falls back to container.json when session and group are null', () => {
+    expect(resolveProviderName(null, null, 'opencode')).toBe('opencode');
+  });
+
+  it('defaults to claude when nothing is set', () => {
+    expect(resolveProviderName(null, null, undefined)).toBe('claude');
+  });
+
+  it('lowercases the resolved name', () => {
+    expect(resolveProviderName('CODEX', null, null)).toBe('codex');
+    expect(resolveProviderName(null, 'OpenCode', null)).toBe('opencode');
+    expect(resolveProviderName(null, null, 'Claude')).toBe('claude');
+  });
+
+  it('treats empty string as unset (falls through)', () => {
+    expect(resolveProviderName('', 'codex', null)).toBe('codex');
+    expect(resolveProviderName(null, '', 'opencode')).toBe('opencode');
+  });
+});