@openparachute/agent 0.1.2 → 0.2.0

package/src/mcp/tools/sessions.ts

@@ -1,135 +0,0 @@
-/**
- * MCP tools for the per-session surface — list / get / close. Mirrors
- * `/api/sessions` (and uses the same heartbeat-mtime liveness computation
- * via DEFAULT_ALIVE_THRESHOLD_MS) but calls the internal helpers directly
- * rather than HTTP-round-tripping.
- *
- * `close-session` calls `killContainer` to actually stop the running
- * container. Idempotent: calling again on an already-closed session is
- * a no-op that returns the current view.
- */
-import fs from 'node:fs';
-
-import { getAllAgentGroups } from '../../db/agent-groups.js';
-import { getSession, getSessionsByAgentGroup, updateSession } from '../../db/sessions.js';
-import { killContainer } from '../../container-runner.js';
-import { DEFAULT_ALIVE_THRESHOLD_MS } from '../../parachute/group-status.js';
-import { heartbeatPath } from '../../session-manager.js';
-import type { ToolDef } from '../types.js';
-
-interface SessionView {
-  id: string;
-  agentGroupId: string;
-  agentGroupFolder: string;
-  agentGroupName: string;
-  messagingGroupId: string | null;
-  status: 'active' | 'closed';
-  containerStatus: 'running' | 'idle' | 'stopped';
-  alive: boolean;
-  createdAt: string;
-  lastActiveAt: string | null;
-  lastHeartbeatAt: string | null;
-}
-
-function readHeartbeatMtimeMs(agentGroupId: string, sessionId: string): number {
-  try {
-    return fs.statSync(heartbeatPath(agentGroupId, sessionId)).mtimeMs;
-  } catch {
-    return 0;
-  }
-}
-
-function listAllSessions(opts: { folder?: string; status?: 'active' | 'closed' } = {}): SessionView[] {
-  const nowMs = Date.now();
-  const out: SessionView[] = [];
-  for (const group of getAllAgentGroups()) {
-    if (opts.folder && group.folder !== opts.folder) continue;
-    for (const s of getSessionsByAgentGroup(group.id)) {
-      if (opts.status && s.status !== opts.status) continue;
-      const heartbeatMs = readHeartbeatMtimeMs(group.id, s.id);
-      const alive = heartbeatMs > 0 && nowMs - heartbeatMs <= DEFAULT_ALIVE_THRESHOLD_MS;
-      out.push({
-        id: s.id,
-        agentGroupId: group.id,
-        agentGroupFolder: group.folder,
-        agentGroupName: group.name,
-        messagingGroupId: s.messaging_group_id,
-        status: s.status,
-        containerStatus: s.container_status,
-        alive,
-        createdAt: s.created_at,
-        lastActiveAt: s.last_active,
-        lastHeartbeatAt: heartbeatMs > 0 ? new Date(heartbeatMs).toISOString() : null,
-      });
-    }
-  }
-  out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
-  return out;
-}
-
-export const sessionTools: ToolDef[] = [
-  {
-    name: 'list-sessions',
-    description:
-      'List sessions across the install. Optional filters: folder (one agent group only) and status (active|closed). Liveness uses the heartbeat mtime.',
-    scope: 'agent:read',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        folder: { type: 'string', description: 'Optional agent-group folder filter.' },
-        status: { type: 'string', enum: ['active', 'closed'], description: 'Optional status filter.' },
-      },
-      additionalProperties: false,
-    },
-    handler: async (args) => {
-      const folder = typeof args.folder === 'string' && args.folder.length ? args.folder : undefined;
-      const status = args.status === 'active' || args.status === 'closed' ? args.status : undefined;
-      return { sessions: listAllSessions({ folder, status }) };
-    },
-  },
-  {
-    name: 'get-session',
-    description: 'Look up a single session by id. Throws when the id is unknown.',
-    scope: 'agent:read',
-    inputSchema: {
-      type: 'object',
-      properties: { id: { type: 'string', description: 'Session id.' } },
-      required: ['id'],
-      additionalProperties: false,
-    },
-    handler: async (args) => {
-      const id = String(args.id ?? '');
-      if (!id) throw new Error('id is required');
-      const session = getSession(id);
-      if (!session) throw new Error(`session not found: ${id}`);
-      const all = listAllSessions();
-      const view = all.find((v) => v.id === id);
-      if (!view) throw new Error(`session not found in listing: ${id}`);
-      return view;
-    },
-  },
-  {
-    name: 'close-session',
-    description:
-      "Close a session: mark the row status='closed' and call killContainer to actually stop the container. Idempotent — already-closed sessions return the current view without re-killing.",
-    scope: 'agent:admin',
-    inputSchema: {
-      type: 'object',
-      properties: { id: { type: 'string', description: 'Session id.' } },
-      required: ['id'],
-      additionalProperties: false,
-    },
-    handler: async (args) => {
-      const id = String(args.id ?? '');
-      if (!id) throw new Error('id is required');
-      const session = getSession(id);
-      if (!session) throw new Error(`session not found: ${id}`);
-      if (session.status === 'closed') {
-        return { id, status: 'closed', alreadyClosed: true };
-      }
-      updateSession(id, { status: 'closed', container_status: 'stopped' });
-      killContainer(id, 'closed via mcp');
-      return { id, status: 'closed' };
-    },
-  },
-];

package/src/mcp/types.ts

@@ -1,51 +0,0 @@
-/**
- * Shared types for paraclaw's MCP server. The registry is one flat list of
- * `ToolDef`s built once per request — both stdio and HTTP transports
- * consume the same registry, with scope-filtering and "disabled" gating
- * applied at advertise time and re-checked at call time.
- *
- * Why factory-style scope context: stdio defaults to `agent:admin` (the
- * caller is the operator on the same machine, ambient trust); HTTP derives
- * the strongest agent scope from the JWT's grant. Both paths flow into a
- * `ToolHandlerContext` so individual tool handlers can refuse mutating ops
- * when the caller only holds `agent:read`.
- */
-import type { AgentScope } from '../web/auth.js';
-
-export type { AgentScope };
-
-/**
- * Per-call context handed to a tool handler. `effectiveScope` is the
- * strongest scope the caller has — handlers that mutate state can choose
- * to refuse if it's below their advertised scope (defense-in-depth; the
- * registry already gates list/call by `t.scope`).
- *
- * `callerSubject` is the JWT `sub` for HTTP and a synthetic
- * `mcp:stdio` for the stdio transport. Used by approval-decide-style
- * tools that need an attribution string.
- */
-export interface ToolHandlerContext {
-  effectiveScope: AgentScope;
-  callerSubject: string;
-}
-
-export interface ToolDef {
-  name: string;
-  description: string;
-  /**
-   * JSON Schema for the tool's input. We pass it straight through to the
-   * MCP SDK's tools/list response; the SDK does no validation, so handlers
-   * are expected to defensively coerce / validate the args they care about.
-   */
-  inputSchema: Record<string, unknown>;
-  /** Required scope to advertise + invoke. */
-  scope: AgentScope;
-  /**
-   * If set, the tool is advertised in the registry (for human introspection)
-   * but filtered out of `tools/list` and refused on `tools/call`. Used for
-   * surfaces that depend on paraclaw-server endpoints not yet on this
-   * branch — see tools/oauth.ts and tools/activity.ts.
-   */
-  disabled?: { reason: string };
-  handler: (args: Record<string, unknown>, ctx: ToolHandlerContext) => Promise<unknown>;
-}

package/src/modules/agent-to-agent/agent-route.test.ts

@@ -1,46 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { isSafeAttachmentName } from './agent-route.js';
-
-/**
- * `forwardAttachedFiles` has a filesystem side that's awkward to unit-test
- * without mocking DATA_DIR. The guarantee worth pinning is that the
- * filename validator rejects everything that could escape the inbox dir —
- * `forwardAttachedFiles` runs this guard before any I/O, so traversal is
- * impossible as long as this matrix holds.
- */
-describe('isSafeAttachmentName', () => {
-  it('accepts plain filenames', () => {
-    expect(isSafeAttachmentName('baby-duck.png')).toBe(true);
-    expect(isSafeAttachmentName('file with spaces.pdf')).toBe(true);
-    expect(isSafeAttachmentName('report.v2.docx')).toBe(true);
-    expect(isSafeAttachmentName('.hidden')).toBe(true); // leading dot is fine, just not `.` / `..`
-  });
-
-  it('rejects empty / sentinel values', () => {
-    expect(isSafeAttachmentName('')).toBe(false);
-    expect(isSafeAttachmentName('.')).toBe(false);
-    expect(isSafeAttachmentName('..')).toBe(false);
-  });
-
-  it('rejects path separators', () => {
-    expect(isSafeAttachmentName('../evil.png')).toBe(false);
-    expect(isSafeAttachmentName('/etc/passwd')).toBe(false);
-    expect(isSafeAttachmentName('nested/file.txt')).toBe(false);
-    expect(isSafeAttachmentName('windows\\path.exe')).toBe(false);
-  });
-
-  it('rejects NUL bytes', () => {
-    expect(isSafeAttachmentName('clean\0.png')).toBe(false);
-  });
-
-  it('rejects anything path.basename would strip', () => {
-    expect(isSafeAttachmentName('a/b')).toBe(false);
-    expect(isSafeAttachmentName('./thing')).toBe(false);
-  });
-
-  it('rejects non-string input', () => {
-    expect(isSafeAttachmentName(null as unknown as string)).toBe(false);
-    expect(isSafeAttachmentName(undefined as unknown as string)).toBe(false);
-  });
-});

package/src/modules/agent-to-agent/agent-route.ts

@@ -1,223 +0,0 @@
-/**
- * Agent-to-agent message routing.
- *
- * Outbound messages with `channel_type === 'agent'` target another agent
- * group rather than a channel. Permission is enforced via `agent_destinations` —
- * the source agent must have a row for the target. Content is copied into the
- * target's inbound DB; if the source message had `files` (from `send_file`),
- * the actual bytes are copied from the source's outbox into the target's
- * `inbox/<a2a-msg-id>/` directory and surfaced to the target agent as
- * `attachments` (existing formatter convention — see formatter.ts:230).
- * The target agent can then forward the file onward via its own `send_file`
- * call using the absolute `/workspace/inbox/<a2a-msg-id>/<filename>` path.
- *
- * Self-messages are always allowed (used for system notes injected back into
- * an agent's own session, e.g. post-approval follow-up prompts).
- *
- * Core delivery.ts dispatches into this via a dynamic import guarded by a
- * `channel_type === 'agent'` check. When the module is absent the check in
- * core throws with a "module not installed" message so retry → mark failed.
- */
-import fs from 'fs';
-import path from 'path';
-
-import { getAgentGroup } from '../../db/agent-groups.js';
-import { getSession } from '../../db/sessions.js';
-import { wakeContainer } from '../../container-runner.js';
-import { log } from '../../log.js';
-import { resolveSession, sessionDir, writeSessionMessage } from '../../session-manager.js';
-import type { Session } from '../../types.js';
-import { hasDestination } from './db/agent-destinations.js';
-
-export interface ForwardedAttachment {
-  name: string;
-  filename: string;
-  type: 'file';
-  localPath: string;
-}
-
-/**
- * Is `name` safe to use as the last segment of a path inside the target
- * agent's inbox directory? Filenames arrive in messages_out content from
- * the source agent — under a multi-agent setup with heterogenous providers
- * (or a compromised / hallucinating sub-agent) they can't be trusted.
- *
- * Rejects:
- *   - empty string
- *   - `.` / `..` (traversal sentinels that path.basename returns as-is)
- *   - anything containing a path separator (`/` or `\`) or NUL
- *   - any value where `path.basename(name) !== name`, catching OS-specific
- *     separators and covering drives/prefixes on Windows runtimes
- */
-export function isSafeAttachmentName(name: string): boolean {
-  if (typeof name !== 'string' || name.length === 0) return false;
-  if (name === '.' || name === '..') return false;
-  if (/[\\/\0]/.test(name)) return false;
-  return path.basename(name) === name;
-}
-
-/**
- * Copy file attachments from the source agent's outbox into the target
- * agent's inbox. Returns attachments using the formatter's existing
- * `{name, type, localPath}` convention — target agent reads `localPath`
- * as relative to `/workspace/`, matching how channel-inbound attachments
- * are surfaced today.
- *
- * Missing source files and unsafe (path-traversal) filenames are skipped
- * with a warning rather than failing the whole route — a bad filename
- * reference shouldn't kill the accompanying text.
- */
-export function forwardAttachedFiles(
-  source: { agentGroupId: string; sessionId: string; messageId: string; filenames: string[] },
-  target: { agentGroupId: string; sessionId: string; messageId: string },
-): ForwardedAttachment[] {
-  if (source.filenames.length === 0) return [];
-
-  const sourceDir = path.join(sessionDir(source.agentGroupId, source.sessionId), 'outbox', source.messageId);
-  if (!fs.existsSync(sourceDir)) {
-    log.warn('agent-route: source outbox dir missing, no files forwarded', {
-      sourceMsgId: source.messageId,
-      sourceDir,
-    });
-    return [];
-  }
-
-  const targetInboxDir = path.join(sessionDir(target.agentGroupId, target.sessionId), 'inbox', target.messageId);
-  fs.mkdirSync(targetInboxDir, { recursive: true });
-
-  const attachments: ForwardedAttachment[] = [];
-  for (const filename of source.filenames) {
-    if (!isSafeAttachmentName(filename)) {
-      log.warn('agent-route: rejecting unsafe attachment filename (path traversal attempt?)', {
-        sourceMsgId: source.messageId,
-        filename,
-      });
-      continue;
-    }
-    const src = path.join(sourceDir, filename);
-    if (!fs.existsSync(src)) {
-      log.warn('agent-route: referenced file missing in source outbox, skipped', {
-        sourceMsgId: source.messageId,
-        filename,
-      });
-      continue;
-    }
-    const dst = path.join(targetInboxDir, filename);
-    fs.copyFileSync(src, dst);
-    attachments.push({
-      name: filename,
-      filename,
-      type: 'file',
-      localPath: `inbox/${target.messageId}/${filename}`,
-    });
-  }
-  return attachments;
-}
-
-export interface RoutableAgentMessage {
-  id: string;
-  platform_id: string | null;
-  content: string;
-}
-
-export async function routeAgentMessage(msg: RoutableAgentMessage, session: Session): Promise<void> {
-  const targetAgentGroupId = msg.platform_id;
-  if (!targetAgentGroupId) {
-    throw new Error(`agent-to-agent message ${msg.id} is missing a target agent group id`);
-  }
-  if (
-    targetAgentGroupId !== session.agent_group_id &&
-    !hasDestination(session.agent_group_id, 'agent', targetAgentGroupId)
-  ) {
-    throw new Error(
-      `unauthorized agent-to-agent: ${session.agent_group_id} has no destination for ${targetAgentGroupId}`,
-    );
-  }
-  if (!getAgentGroup(targetAgentGroupId)) {
-    throw new Error(`target agent group ${targetAgentGroupId} not found for message ${msg.id}`);
-  }
-  const { session: targetSession } = resolveSession(targetAgentGroupId, null, null, 'agent-shared');
-  const a2aMsgId = `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-
-  // If the source message references files (via `send_file`), forward the
-  // bytes from the source's outbox into the target's inbox so the target
-  // agent can actually see and re-send them. Without this, agent-to-agent
-  // file attachments look like they arrive but the target has no way to
-  // read the bytes — they live in a session dir it doesn't mount.
-  const forwardedContent = forwardFileAttachments(msg, a2aMsgId, session, targetAgentGroupId, targetSession.id);
-
-  writeSessionMessage(targetAgentGroupId, targetSession.id, {
-    id: a2aMsgId,
-    kind: 'chat',
-    timestamp: new Date().toISOString(),
-    platformId: session.agent_group_id,
-    channelType: 'agent',
-    threadId: null,
-    content: forwardedContent,
-  });
-  log.info('Agent message routed', {
-    from: session.agent_group_id,
-    to: targetAgentGroupId,
-    targetSession: targetSession.id,
-    a2aMsgId,
-    forwardedFileCount: countForwardedFiles(forwardedContent),
-  });
-  const fresh = getSession(targetSession.id);
-  if (fresh) await wakeContainer(fresh);
-}
-
-/**
- * Parse source content, copy any referenced `files` from source outbox to
- * target inbox, and return a JSON string with an `attachments` array added
- * (formatter.ts:223 already knows how to render this shape).
- *
- * If the source content isn't JSON or has no files, returns the original
- * content string unchanged — this is safe to call on every route.
- */
-function forwardFileAttachments(
-  msg: RoutableAgentMessage,
-  a2aMsgId: string,
-  sourceSession: Session,
-  targetAgentGroupId: string,
-  targetSessionId: string,
-): string {
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(msg.content);
-  } catch {
-    return msg.content;
-  }
-  const files = parsed.files as unknown;
-  if (!Array.isArray(files) || files.length === 0) return msg.content;
-  const filenames = files.filter((f): f is string => typeof f === 'string');
-  if (filenames.length === 0) return msg.content;
-
-  const attachments = forwardAttachedFiles(
-    {
-      agentGroupId: sourceSession.agent_group_id,
-      sessionId: sourceSession.id,
-      messageId: msg.id,
-      filenames,
-    },
-    {
-      agentGroupId: targetAgentGroupId,
-      sessionId: targetSessionId,
-      messageId: a2aMsgId,
-    },
-  );
-
-  // Merge into any existing `attachments` (unlikely in a2a context but safe).
-  const existing = Array.isArray(parsed.attachments) ? (parsed.attachments as Record<string, unknown>[]) : [];
-  parsed.attachments = [...existing, ...attachments];
-
-  return JSON.stringify(parsed);
-}
-
-function countForwardedFiles(contentStr: string): number {
-  try {
-    const parsed = JSON.parse(contentStr);
-    return Array.isArray(parsed.attachments) ? parsed.attachments.length : 0;
-  } catch {
-    return 0;
-  }
-}

package/src/modules/agent-to-agent/create-agent.ts

@@ -1,127 +0,0 @@
-/**
- * `create_agent` delivery-action handler.
- *
- * Spawns a new agent group on demand from the parent agent, wires bidirectional
- * agent_destinations rows, projects the new destination into the parent's
- * running container, and notifies the parent.
- */
-import path from 'path';
-
-import { GROUPS_DIR } from '../../config.js';
-import { createAgentGroup, getAgentGroup, getAgentGroupByFolder } from '../../db/agent-groups.js';
-import { getSession } from '../../db/sessions.js';
-import { wakeContainer } from '../../container-runner.js';
-import { initGroupFilesystem } from '../../group-init.js';
-import { log } from '../../log.js';
-import { writeSessionMessage } from '../../session-manager.js';
-import type { AgentGroup, Session } from '../../types.js';
-import { createDestination, getDestinationByName, normalizeName } from './db/agent-destinations.js';
-import { writeDestinations } from './write-destinations.js';
-
-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 async function handleCreateAgent(content: Record<string, unknown>, session: Session): Promise<void> {
-  const requestId = content.requestId as string;
-  const name = content.name as string;
-  const instructions = content.instructions as string | null;
-
-  const sourceGroup = getAgentGroup(session.agent_group_id);
-  if (!sourceGroup) {
-    notifyAgent(session, `create_agent failed: source agent group not found.`);
-    log.warn('create_agent failed: missing source group', { sessionAgentGroup: session.agent_group_id, name });
-    return;
-  }
-
-  const localName = normalizeName(name);
-
-  // Collision in the creator's destination namespace
-  if (getDestinationByName(sourceGroup.id, localName)) {
-    notifyAgent(session, `Cannot create agent "${name}": you already have a destination named "${localName}".`);
-    return;
-  }
-
-  // Derive a safe folder name, deduplicated globally across agent_groups.folder
-  let folder = localName;
-  let suffix = 2;
-  while (getAgentGroupByFolder(folder)) {
-    folder = `${localName}-${suffix}`;
-    suffix++;
-  }
-
-  const groupPath = path.join(GROUPS_DIR, folder);
-  const resolvedPath = path.resolve(groupPath);
-  const resolvedGroupsDir = path.resolve(GROUPS_DIR);
-  if (!resolvedPath.startsWith(resolvedGroupsDir + path.sep)) {
-    notifyAgent(session, `Cannot create agent "${name}": invalid folder path.`);
-    log.error('create_agent path traversal attempt', { folder, resolvedPath });
-    return;
-  }
-
-  const agentGroupId = `ag-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  const now = new Date().toISOString();
-
-  const newGroup: AgentGroup = {
-    id: agentGroupId,
-    name,
-    folder,
-    agent_provider: null,
-    secret_mode: 'selective',
-    created_at: now,
-  };
-  createAgentGroup(newGroup);
-  initGroupFilesystem(newGroup, { instructions: instructions ?? undefined });
-
-  // Insert bidirectional destination rows (= ACL grants).
-  // Creator refers to child by the name it chose; child refers to creator as "parent".
-  createDestination({
-    agent_group_id: sourceGroup.id,
-    local_name: localName,
-    target_type: 'agent',
-    target_id: agentGroupId,
-    created_at: now,
-  });
-  // Handle the unlikely case where the child already has a "parent" destination
-  // (shouldn't happen for a brand-new agent, but be safe).
-  let parentName = 'parent';
-  let parentSuffix = 2;
-  while (getDestinationByName(agentGroupId, parentName)) {
-    parentName = `parent-${parentSuffix}`;
-    parentSuffix++;
-  }
-  createDestination({
-    agent_group_id: agentGroupId,
-    local_name: parentName,
-    target_type: 'agent',
-    target_id: sourceGroup.id,
-    created_at: now,
-  });
-
-  // REQUIRED: project the new destination into the running container's
-  // inbound.db. See the top-of-file invariant in db/agent-destinations.ts
-  // — forgetting this causes "dropped: unknown destination" when the parent
-  // tries to send to the newly-created child.
-  writeDestinations(session.agent_group_id, session.id);
-
-  // Fire-and-forget notification back to the creator
-  notifyAgent(
-    session,
-    `Agent "${localName}" created. You can now message it with <message to="${localName}">...</message>.`,
-  );
-  log.info('Agent group created', { agentGroupId, name, localName, folder, parent: sourceGroup.id });
-  // Note: requestId is unused — this is fire-and-forget, not request/response.
-  void requestId;
-}