@openparachute/agent 0.1.0

package/src/mcp/tools/sessions.ts

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

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

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

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

@@ -0,0 +1,127 @@
+/**
+ * `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;
+}