@openparachute/agent 0.1.2 → 0.2.0

package/src/command-gate.ts

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

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

@@ -1,128 +0,0 @@
-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. Captured once at module load
-// (process.cwd() at boot — the right value for the install dir) so every
-// downstream consumer agrees on a single resolved root, and tests that
-// chdir() can't desync against it. Exported for surfaces that need to
-// self-register the install path (e.g. services.json `installDir`,
-// paraclaw#115).
-export const PROJECT_ROOT = process.cwd();
-// Operator's home dir. Resolved once at module load — every downstream
-// consumer that needs to expand `~` or derive a HOME-relative path imports
-// this rather than calling `os.homedir()` itself, so a future precedence
-// change (e.g. add a `PARACHUTE_AGENT_HOME` override) is one edit. Honors
-// `HOME` env var first (sandbox-friendly, matches POSIX convention) before
-// falling back to the real home dir.
-export 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.
-//
-// Note (paraclaw#99): the allowlist sits at `<HOME>/.config/parachute-agent/`,
-// NOT under `PARACHUTE_DIR`. This is intentional — the file is operator-host
-// policy ("which paths can the agent ever mount on this host"), not runtime
-// state of any one install. Two installs sharing a host should agree on the
-// allowlist; a sandbox at `PARACHUTE_HOME=/tmp/sandbox` deliberately reads
-// the same file the live install does. Runtime state (central DB +
-// master.key) routes through `PARACHUTE_DIR` instead — see CENTRAL_DB_DIR
-// below and the sandbox-isolation block in CLAUDE.md.
-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

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

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