@openparachute/agent 0.1.1 → 0.2.0

package/scripts/init-first-agent.ts

@@ -1,377 +0,0 @@
-/**
- * Init the first (or Nth) Paraclaw agent for a DM channel.
- *
- * Wires a real DM channel (discord, telegram, etc.) to a new agent group,
- * then hands a welcome message to the running service via the CLI socket
- * (admin transport). The service routes that message into the DM session,
- * which wakes the container synchronously — the agent processes the welcome
- * and DMs the operator through the normal delivery path.
- *
- * CLI channel wiring is handled separately by `scripts/init-cli-agent.ts`.
- *
- * Creates/reuses: user, owner grant (if none), agent group + filesystem,
- * messaging group(s), wiring.
- *
- * Runs alongside the service (WAL-mode sqlite + CLI socket IPC) — does NOT
- * initialize channel adapters, so there's no Gateway conflict. Requires
- * the service to be running: the welcome hand-off goes over the CLI socket
- * and fails loudly if the service isn't up.
- *
- * Usage:
- *   pnpm exec tsx scripts/init-first-agent.ts \
- *     --channel discord \
- *     --user-id discord:1470183333427675709 \
- *     --platform-id discord:@me:1491573333382523708 \
- *     --display-name "Gavriel" \
- *     [--agent-name "Andy"] \
- *     [--welcome "System instruction: ..."] \
- *     [--role owner|admin|member]    # default: owner
- *
- * For direct-addressable channels (telegram, whatsapp, etc.), --platform-id
- * is typically the same as the handle in --user-id, with the channel prefix.
- */
-import net from 'net';
-import path from 'path';
-
-import { CENTRAL_DB_PATH, DATA_DIR } from '../src/config.js';
-import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
-import { initDb, migrateCentralDbLocation } from '../src/db/connection.js';
-import {
-  createMessagingGroup,
-  createMessagingGroupAgent,
-  getMessagingGroupAgentByPair,
-  getMessagingGroupByPlatform,
-} from '../src/db/messaging-groups.js';
-import { runMigrations } from '../src/db/migrations/index.js';
-import { normalizeName } from '../src/modules/agent-to-agent/db/agent-destinations.js';
-import { addMember } from '../src/modules/permissions/db/agent-group-members.js';
-import { getUserRoles, grantRole } from '../src/modules/permissions/db/user-roles.js';
-import { upsertUser } from '../src/modules/permissions/db/users.js';
-import { initGroupFilesystem } from '../src/group-init.js';
-import { namespacedPlatformId } from '../src/platform-id.js';
-import type { AgentGroup, MessagingGroup } from '../src/types.js';
-
-type Role = 'owner' | 'admin' | 'member';
-
-interface Args {
-  channel: string;
-  userId: string;
-  platformId: string;
-  displayName: string;
-  agentName: string;
-  welcome: string;
-  role: Role;
-}
-
-const DEFAULT_WELCOME =
-  'System instruction: run /welcome to introduce yourself to the user on this new channel.';
-
-const DEFAULT_ROLE: Role = 'owner';
-
-function parseArgs(argv: string[]): Args {
-  const out: Partial<Args> = {};
-  for (let i = 0; i < argv.length; i++) {
-    const key = argv[i];
-    const val = argv[i + 1];
-    switch (key) {
-      case '--channel':
-        out.channel = (val ?? '').toLowerCase();
-        i++;
-        break;
-      case '--user-id':
-        out.userId = val;
-        i++;
-        break;
-      case '--platform-id':
-        out.platformId = val;
-        i++;
-        break;
-      case '--display-name':
-        out.displayName = val;
-        i++;
-        break;
-      case '--agent-name':
-        out.agentName = val;
-        i++;
-        break;
-      case '--welcome':
-        out.welcome = val;
-        i++;
-        break;
-      case '--role': {
-        const raw = (val ?? '').toLowerCase();
-        if (raw !== 'owner' && raw !== 'admin' && raw !== 'member') {
-          console.error(
-            `Invalid --role: ${raw} (expected 'owner', 'admin', or 'member')`,
-          );
-          process.exit(2);
-        }
-        out.role = raw;
-        i++;
-        break;
-      }
-    }
-  }
-
-  const required: (keyof Args)[] = ['channel', 'userId', 'platformId', 'displayName'];
-  const missing = required.filter((k) => !out[k]);
-  if (missing.length) {
-    console.error(
-      `Missing required args: ${missing.map((k) => `--${k.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}`,
-    );
-    console.error('See scripts/init-first-agent.ts header for usage.');
-    process.exit(2);
-  }
-
-  return {
-    channel: out.channel!,
-    userId: out.userId!,
-    platformId: out.platformId!,
-    displayName: out.displayName!,
-    agentName: out.agentName?.trim() || out.displayName!,
-    welcome: out.welcome?.trim() || DEFAULT_WELCOME,
-    role: out.role ?? DEFAULT_ROLE,
-  };
-}
-
-function namespacedUserId(channel: string, raw: string): string {
-  return raw.includes(':') ? raw : `${channel}:${raw}`;
-}
-
-function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-function wireIfMissing(mg: MessagingGroup, ag: AgentGroup, now: string, label: string): void {
-  const existing = getMessagingGroupAgentByPair(mg.id, ag.id);
-  if (existing) {
-    console.log(`Wiring already exists: ${existing.id} (${label})`);
-    return;
-  }
-  createMessagingGroupAgent({
-    id: generateId('mga'),
-    messaging_group_id: mg.id,
-    agent_group_id: ag.id,
-    // DM / CLI (is_group=0) default to "respond to everything" via a '.' regex.
-    // Group chats default to mention-only; admins can upgrade to mention-sticky
-    // via /manage-channels once the agent is in use.
-    engage_mode: mg.is_group === 0 ? 'pattern' : 'mention',
-    engage_pattern: mg.is_group === 0 ? '.' : null,
-    sender_scope: 'all',
-    ignored_message_policy: 'drop',
-    session_mode: 'shared',
-    priority: 0,
-    created_at: now,
-  });
-  console.log(`Wired ${label}: ${mg.id} -> ${ag.id}`);
-}
-
-async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2));
-
-  migrateCentralDbLocation();
-  const db = initDb(CENTRAL_DB_PATH);
-  runMigrations(db); // idempotent
-
-  const now = new Date().toISOString();
-
-  // 1. User + (conditional) owner grant.
-  const userId = namespacedUserId(args.channel, args.userId);
-  upsertUser({
-    id: userId,
-    kind: args.channel,
-    display_name: args.displayName,
-    created_at: now,
-  });
-
-  // Owner grant is deferred until after the agent group is resolved, since
-  // an admin grant is scoped to that group. See step 2b.
-
-  // 2. Agent group + filesystem.
-  const folder = `dm-with-${normalizeName(args.displayName)}`;
-  let ag: AgentGroup | undefined = getAgentGroupByFolder(folder);
-  if (!ag) {
-    const agId = generateId('ag');
-    createAgentGroup({
-      id: agId,
-      name: args.agentName,
-      folder,
-      agent_provider: null,
-      created_at: now,
-    });
-    ag = getAgentGroupByFolder(folder)!;
-    console.log(`Created agent group: ${ag.id} (${folder})`);
-  } else {
-    console.log(`Reusing agent group: ${ag.id} (${folder})`);
-  }
-  initGroupFilesystem(ag, {
-    instructions:
-      `# ${args.agentName}\n\n` +
-      `You are ${args.agentName}, a personal Paraclaw agent for ${args.displayName}. ` +
-      'When the user first reaches out (or you receive a system welcome prompt), introduce yourself briefly and invite them to chat. Keep replies concise.',
-  });
-
-  // 2b. Assign the user a role for this agent group. The caller picks via
-  // --role; the channel drivers default to 'owner' for the self-host case.
-  //  - owner:  global owner (agent_group_id=null). Cross-channel access.
-  //  - admin:  scoped admin for this agent group only.
-  //  - member: no role grant, just the membership row below.
-  // grantRole inserts a new row per call — idempotence check against
-  // getUserRoles prevents duplicates on re-runs.
-  const existingRoles = getUserRoles(userId);
-  if (args.role === 'owner') {
-    const alreadyOwner = existingRoles.some(
-      (r) => r.role === 'owner' && r.agent_group_id === null,
-    );
-    if (!alreadyOwner) {
-      grantRole({
-        user_id: userId,
-        role: 'owner',
-        agent_group_id: null,
-        granted_by: null,
-        granted_at: now,
-      });
-    }
-  } else if (args.role === 'admin') {
-    const alreadyAdmin = existingRoles.some(
-      (r) => r.role === 'admin' && r.agent_group_id === ag.id,
-    );
-    if (!alreadyAdmin) {
-      grantRole({
-        user_id: userId,
-        role: 'admin',
-        agent_group_id: ag.id,
-        granted_by: null,
-        granted_at: now,
-      });
-    }
-  }
-
-  // Always add a membership row so the access gate has a straightforward
-  // yes/no even for users without a role grant. INSERT OR IGNORE, so this
-  // is a no-op when the row already exists (e.g. re-runs, owners whose
-  // access already passes via role).
-  addMember({
-    user_id: userId,
-    agent_group_id: ag.id,
-    added_by: null,
-    added_at: now,
-  });
-
-  // 3. DM messaging group.
-  const platformId = namespacedPlatformId(args.channel, args.platformId);
-  let dmMg = getMessagingGroupByPlatform(args.channel, platformId);
-  if (!dmMg) {
-    const mgId = generateId('mg');
-    createMessagingGroup({
-      id: mgId,
-      channel_type: args.channel,
-      platform_id: platformId,
-      name: args.displayName,
-      is_group: 0,
-      unknown_sender_policy: 'strict',
-      created_at: now,
-    });
-    dmMg = getMessagingGroupByPlatform(args.channel, platformId)!;
-    console.log(`Created messaging group: ${dmMg.id} (${platformId})`);
-  } else {
-    console.log(`Reusing messaging group: ${dmMg.id} (${platformId})`);
-  }
-
-  // 4. Wire DM messaging group to the agent.
-  wireIfMissing(dmMg, ag, now, 'dm');
-
-  // 5. Welcome delivery over the CLI socket. Router picks up the line,
-  // writes the message into the DM session's inbound.db, and wakes the
-  // container synchronously — no sweep wait. The paired user's identity is
-  // passed so the sender resolver sees the real owner, not cli:local.
-  await sendWelcomeViaCliSocket(dmMg, args.welcome, {
-    senderId: userId,
-    sender: args.displayName,
-  });
-
-  const roleLabel =
-    args.role === 'owner'
-      ? 'owner (global)'
-      : args.role === 'admin'
-        ? `admin (scoped to ${ag.id})`
-        : 'member';
-
-  console.log('');
-  console.log('Init complete.');
-  console.log(`  user:    ${userId}`);
-  console.log(`  role:    ${roleLabel}`);
-  console.log(`  agent:   ${ag.name} [${ag.id}] @ groups/${folder}`);
-  console.log(`  channel: ${args.channel} ${dmMg.platform_id}`);
-  console.log('');
-  console.log('Welcome DM queued — the agent will greet you shortly.');
-}
-
-/**
- * Hand the welcome to the running service via its CLI Unix socket. The
- * service's CLI adapter receives `{text, to}`, builds an InboundEvent
- * targeting the DM messaging group, and calls routeInbound(). Router writes
- * the message into inbound.db and wakes the container synchronously.
- *
- * Throws if the socket isn't reachable — this script requires the service
- * to be running.
- */
-async function sendWelcomeViaCliSocket(
-  dmMg: MessagingGroup,
-  welcome: string,
-  identity: { senderId: string; sender: string },
-): Promise<void> {
-  const sockPath = path.join(DATA_DIR, 'cli.sock');
-
-  await new Promise<void>((resolve, reject) => {
-    const socket = net.connect(sockPath);
-    let settled = false;
-
-    const settle = (err: Error | null) => {
-      if (settled) return;
-      settled = true;
-      try {
-        socket.end();
-      } catch {
-        /* noop */
-      }
-      if (err) reject(err);
-      else resolve();
-    };
-
-    socket.once('error', (err) =>
-      settle(
-        new Error(
-          `CLI socket at ${sockPath} not reachable: ${err.message}. Is the Paraclaw service running?`,
-        ),
-      ),
-    );
-    socket.once('connect', () => {
-      const payload =
-        JSON.stringify({
-          text: welcome,
-          senderId: identity.senderId,
-          sender: identity.sender,
-          to: {
-            channelType: dmMg.channel_type,
-            platformId: dmMg.platform_id,
-            threadId: dmMg.platform_id,
-          },
-        }) + '\n';
-      socket.write(payload, (err) => {
-        if (err) {
-          settle(err);
-          return;
-        }
-        // Brief flush delay so the router picks up the line before we close.
-        // Router handles it synchronously once read, so 50ms is plenty.
-        setTimeout(() => settle(null), 50);
-      });
-    });
-  });
-}
-
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
-  process.exit(1);
-});

package/scripts/parachute.ts

@@ -1,158 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Paraclaw — Parachute integration CLI.
- *
- *   pnpm run parachute attach-vault <group> --token pvt_… [--scope vault:read] [--vault-url URL]
- *   pnpm run parachute detach-vault <group> [--name parachute-vault]
- *   pnpm run parachute status [<group>]
- *
- * Wires (or unwires) a Parachute Vault as an HTTP MCP server in the named
- * agent group's `container.json`, and records the attachment metadata in a
- * sibling `parachute.json` for visibility / future tooling.
- *
- * The CLI does NOT mint vault tokens — that's the user's job, via:
- *
- *   parachute vault tokens create --scope vault:read --label claw-<group>
- *
- * Once you have a `pvt_…` token, paste it here. Detach also doesn't revoke
- * tokens — see vault-mcp.ts comments for why (one-way op; deliberate).
- */
-import fs from 'fs';
-import path from 'path';
-
-import { GROUPS_DIR } from '../src/config.js';
-import {
-  DEFAULT_VAULT_MCP_NAME,
-  attachVaultToGroup,
-  detachVaultFromGroup,
-  readVaultAttachment,
-} from '../src/parachute/vault-mcp.js';
-import type { VaultScope } from '../src/parachute/types.js';
-
-const SUBCOMMANDS = ['attach-vault', 'detach-vault', 'status'] as const;
-type Subcommand = (typeof SUBCOMMANDS)[number];
-
-function usage(exit = 0): never {
-  console.error(`usage:
-  pnpm run parachute attach-vault <group> --token <pvt_...> [--scope vault:read|vault:write|vault:admin]
-                                          [--vault-url http://127.0.0.1:1940/vault/default]
-                                          [--label <token-label>] [--name <mcp-name>]
-  pnpm run parachute detach-vault <group> [--name parachute-vault]
-  pnpm run parachute status [<group>]
-
-Notes:
-  - Mint a token with: parachute vault tokens create --scope vault:read --label claw-<group>
-  - --vault-url defaults to http://127.0.0.1:1940/vault/default
-  - --scope defaults to vault:read (the safest default; granted scope is recorded only)
-  - --name defaults to '${DEFAULT_VAULT_MCP_NAME}' (the key under mcpServers)
-`);
-  process.exit(exit);
-}
-
-function arg(name: string, args: string[]): string | undefined {
-  const i = args.indexOf(`--${name}`);
-  return i >= 0 ? args[i + 1] : undefined;
-}
-
-function parseScope(s: string | undefined): VaultScope {
-  const allowed: VaultScope[] = ['vault:read', 'vault:write', 'vault:admin'];
-  if (!s) return 'vault:read';
-  if ((allowed as string[]).includes(s)) return s as VaultScope;
-  console.error(`unrecognized scope "${s}". Allowed: ${allowed.join(', ')}`);
-  process.exit(2);
-}
-
-function listGroupFolders(): string[] {
-  if (!fs.existsSync(GROUPS_DIR)) return [];
-  return fs
-    .readdirSync(GROUPS_DIR, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name);
-}
-
-function main(): void {
-  const [, , raw, ...rest] = process.argv;
-  if (!raw || raw === '--help' || raw === '-h') usage(0);
-  if (!(SUBCOMMANDS as readonly string[]).includes(raw)) {
-    console.error(`unknown subcommand: ${raw}\n`);
-    usage(2);
-  }
-  const sub = raw as Subcommand;
-
-  if (sub === 'attach-vault') {
-    const group = rest[0];
-    if (!group) {
-      console.error('attach-vault requires <group> as the first positional argument.');
-      usage(2);
-    }
-    const token = arg('token', rest);
-    if (!token) {
-      console.error('attach-vault requires --token <pvt_...>');
-      usage(2);
-    }
-    const vaultBaseUrl = arg('vault-url', rest) ?? 'http://127.0.0.1:1940/vault/default';
-    const scope = parseScope(arg('scope', rest));
-    const tokenLabel = arg('label', rest) ?? `claw-${group}`;
-    const mcpName = arg('name', rest);
-
-    attachVaultToGroup({
-      folder: group,
-      vaultBaseUrl,
-      vaultToken: token,
-      scope,
-      tokenLabel,
-      mcpName,
-      instructions: `You have access to a Parachute Vault at ${vaultBaseUrl} via the \`${mcpName ?? DEFAULT_VAULT_MCP_NAME}\` MCP server. Scope: ${scope}. The vault is the user's open knowledge graph — notes, tags, links. Use it as you would any tool: query when you need context, write when you have something durable to capture. The user decides how their vault is organized; respect that.`,
-    });
-
-    console.log(`✓ vault attached to group "${group}"`);
-    console.log(`  vault: ${vaultBaseUrl}`);
-    console.log(`  scope: ${scope}`);
-    console.log(`  token label: ${tokenLabel}  (revoke with: parachute vault tokens revoke ${tokenLabel})`);
-    console.log(`  mcp name: ${mcpName ?? DEFAULT_VAULT_MCP_NAME}`);
-    console.log('');
-    console.log('Next: restart the agent\'s container so it picks up the new MCP entry.');
-    console.log(`  (or just send the next message — Paraclaw spawns lazily on wake.)`);
-    return;
-  }
-
-  if (sub === 'detach-vault') {
-    const group = rest[0];
-    if (!group) {
-      console.error('detach-vault requires <group> as the first positional argument.');
-      usage(2);
-    }
-    const mcpName = arg('name', rest) ?? DEFAULT_VAULT_MCP_NAME;
-    detachVaultFromGroup(group, mcpName);
-    console.log(`✓ vault detached from group "${group}" (mcp: ${mcpName})`);
-    console.log(`  Token NOT revoked — run: parachute vault tokens revoke <label>`);
-    return;
-  }
-
-  if (sub === 'status') {
-    const target = rest[0];
-    const groups = target ? [target] : listGroupFolders();
-    if (groups.length === 0) {
-      console.log('no agent groups found in', GROUPS_DIR);
-      return;
-    }
-    let any = false;
-    for (const g of groups) {
-      const att = readVaultAttachment(g);
-      if (!att) {
-        if (target) console.log(`${g}: no vault attached`);
-        continue;
-      }
-      any = true;
-      console.log(`${g}:`);
-      console.log(`  vault: ${att.vaultBaseUrl}`);
-      console.log(`  scope: ${att.scope}`);
-      console.log(`  token label: ${att.tokenLabel}`);
-      console.log(`  attached: ${att.attachedAt}`);
-    }
-    if (!any && !target) console.log('no agent groups have a vault attached.');
-    return;
-  }
-}
-
-main();

package/scripts/run-migrations.ts

@@ -1,105 +0,0 @@
-#!/usr/bin/env tsx
-import { execFileSync, execSync } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-
-function compareSemver(a: string, b: string): number {
-  const partsA = a.split('.').map(Number);
-  const partsB = b.split('.').map(Number);
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    const diff = (partsA[i] || 0) - (partsB[i] || 0);
-    if (diff !== 0) return diff;
-  }
-  return 0;
-}
-
-// Resolve tsx binary once to avoid npx race conditions across migrations
-function resolveTsx(): string {
-  // Check local node_modules first
-  const local = path.resolve('node_modules/.bin/tsx');
-  if (fs.existsSync(local)) return local;
-  // Fall back to whichever tsx is in PATH
-  try {
-    return execSync('which tsx', { encoding: 'utf-8' }).trim();
-  } catch {
-    return 'npx'; // last resort
-  }
-}
-
-const tsxBin = resolveTsx();
-
-const fromVersion = process.argv[2];
-const toVersion = process.argv[3];
-const newCorePath = process.argv[4];
-
-if (!fromVersion || !toVersion || !newCorePath) {
-  console.error(
-    'Usage: tsx scripts/run-migrations.ts <from-version> <to-version> <new-core-path>',
-  );
-  process.exit(1);
-}
-
-interface MigrationResult {
-  version: string;
-  success: boolean;
-  error?: string;
-}
-
-const results: MigrationResult[] = [];
-
-// Look for migrations in the new core
-const migrationsDir = path.join(newCorePath, 'migrations');
-
-if (!fs.existsSync(migrationsDir)) {
-  console.log(JSON.stringify({ migrationsRun: 0, results: [] }, null, 2));
-  process.exit(0);
-}
-
-// Discover migration directories (version-named)
-const entries = fs.readdirSync(migrationsDir, { withFileTypes: true });
-const migrationVersions = entries
-  .filter((e) => e.isDirectory() && /^\d+\.\d+\.\d+$/.test(e.name))
-  .map((e) => e.name)
-  .filter(
-    (v) =>
-      compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0,
-  )
-  .sort(compareSemver);
-
-const projectRoot = process.cwd();
-
-for (const version of migrationVersions) {
-  const migrationIndex = path.join(migrationsDir, version, 'index.ts');
-  if (!fs.existsSync(migrationIndex)) {
-    results.push({
-      version,
-      success: false,
-      error: `Migration ${version}/index.ts not found`,
-    });
-    continue;
-  }
-
-  try {
-    const tsxArgs = tsxBin.endsWith('npx')
-      ? ['tsx', migrationIndex, projectRoot]
-      : [migrationIndex, projectRoot];
-    execFileSync(tsxBin, tsxArgs, {
-      stdio: 'pipe',
-      cwd: projectRoot,
-      timeout: 120_000,
-    });
-    results.push({ version, success: true });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    results.push({ version, success: false, error: message });
-  }
-}
-
-console.log(
-  JSON.stringify({ migrationsRun: results.length, results }, null, 2),
-);
-
-// Exit with error if any migration failed
-if (results.some((r) => !r.success)) {
-  process.exit(1);
-}