feat: Import & Export Agent Teams

[mrgoonie]

Summary

Add the ability to export an agent team (with its members, settings, tasks, and workspace files) to a portable JSON bundle, and import that bundle into another GoClaw instance (or the same instance for duplication/backup).

Motivation

• Portability: Move a fully configured team between environments (dev → staging → prod).
• Backup & Restore: Snapshot a team before destructive changes.
• Template Sharing: Export a team blueprint (without user-specific data) for others to bootstrap from.
• Multi-Tenant Migration: Transfer teams across tenants.

Current State

Teams are managed entirely via WebSocket RPC (teams.* methods). There is no existing import/export mechanism for teams. Agents have CRUD via RPC but no bulk export either. The closest pattern is teams.tasks.delete-bulk for batch operations.

Data Model (current)

erDiagram
    agent_teams ||--o{ agent_team_members : "has members"
    agent_teams ||--o{ team_tasks : "has tasks"
    agent_teams ||--o{ team_user_grants : "grants access"
    agent_teams ||--o{ agent_links : "auto-created links"
    agent_teams ||--o{ team_workspace_files : "workspace"
    agent_team_members }o--|| agents : "references"
    team_tasks ||--o{ team_task_comments : "has comments"
    team_tasks ||--o{ team_task_events : "audit trail"
    team_tasks ||--o{ team_task_attachments : "file refs"
    team_workspace_files ||--o{ team_workspace_file_versions : "versions"

    agent_teams {
        uuid id PK
        string name
        uuid lead_agent_id FK
        string description
        string status
        jsonb settings
        uuid tenant_id
    }
    agent_team_members {
        uuid team_id FK
        uuid agent_id FK
        string role
    }
    team_tasks {
        uuid id PK
        uuid team_id FK
        string subject
        string status
        uuid owner_agent_id
        int task_number
    }
    agents {
        uuid id PK
        string key
        string name
        string agent_type
    }

Loading

Proposed Approach

Export Flow

flowchart TD
    A[User triggers export] --> B{Export mode?}
    B -->|full| C[Collect team + members + tasks + workspace + settings]
    B -->|template| D[Collect team + members + settings only]
    B -->|snapshot| E[Collect everything + task events + comments]

    C --> F[Resolve agent references]
    D --> F
    E --> F

    F --> G{Include agent definitions?}
    G -->|yes| H[Embed agent configs, context files, skills]
    G -->|no| I[Store agent keys as references only]

    H --> J[Build export bundle]
    I --> J

    J --> K[Add metadata: version, timestamp, source tenant]
    K --> L[Validate and serialize to JSON]
    L --> M[Return downloadable bundle]

    style A fill:#e1f5fe
    style M fill:#c8e6c9

Loading

Import Flow

flowchart TD
    A[User uploads bundle] --> B[Parse and validate schema version]
    B --> C{Schema compatible?}
    C -->|no| D[Reject with version mismatch error]
    C -->|yes| E[Resolve agent references]

    E --> F{Agent exists in target?}
    F -->|yes| G[Map to existing agent by key]
    F -->|no| H{Include agent defs?}
    H -->|yes| I[Create agent from embedded config]
    H -->|no| J[Prompt user to map manually]

    G --> K[Create team with resolved agents]
    I --> K
    J --> K

    K --> L{Import mode?}
    L -->|merge| M[Merge into existing team]
    L -->|create| N[Create as new team]

    N --> O[Import tasks if present]
    M --> O
    O --> P[Import workspace files if present]
    P --> Q[Auto-create agent links]
    Q --> R[Broadcast team.created events]
    R --> S[Return import summary report]

    style A fill:#e1f5fe
    style D fill:#ffcdd2
    style S fill:#c8e6c9

Loading

Export Bundle Schema (draft)

{
  "version": "1.0",
  "exported_at": "2026-03-23T12:00:00Z",
  "source_instance": "goclaw-prod",
  "source_tenant_id": "uuid",
  "export_mode": "full|template|snapshot",
  "team": {
    "name": "...",
    "description": "...",
    "status": "active",
    "settings": { "..." : "..." }
  },
  "members": [
    {
      "role": "lead|member|reviewer",
      "agent_key": "agent-key-ref",
      "agent": { "...embedded agent config if included..." : "" }
    }
  ],
  "tasks": [],
  "workspace_files": []
}

API Surface

RPC Methods (WebSocket)

Method	Description
teams.export	Export team to JSON bundle
teams.import	Import team from JSON bundle
teams.import.preview	Dry-run: validate bundle and show what will be created

HTTP Endpoints

Method	Path	Description
GET	/v1/teams/{id}/export	Download team export as JSON file
POST	/v1/teams/import	Upload and import team bundle
POST	/v1/teams/import/preview	Validate bundle without importing

CLI

Command	Description
goclaw teams export <team-id>	Export team to stdout/file
goclaw teams import <file>	Import team from file

Implementation Phases

Phase 1: Export (core)

• Define bundle JSON schema with version field
• Implement TeamStore.Export() that collects team + members + settings
• Add teams.export RPC method
• Add GET /v1/teams/{id}/export HTTP endpoint
• Support template mode (no tasks/workspace)

Phase 2: Import (core)

• Implement bundle validation and schema version check
• Agent reference resolution (by key match or embedded config)
• Implement TeamStore.Import() with transaction safety
• Add teams.import + teams.import.preview RPC methods
• Add POST /v1/teams/import HTTP endpoint

Phase 3: Full mode + CLI

• Export/import tasks with comments and events
• Export/import workspace files (with versions)
• Add goclaw teams export/import CLI commands
• Add Web UI export/import buttons

Phase 4: Cross-tenant and advanced

• Cross-tenant import with tenant remapping
• Conflict resolution strategies (skip/overwrite/rename)
• Incremental export (changes since last export)

Considerations

• Agent identity: Agents are identified by key (unique per tenant). Import must handle key collisions.
• UUID regeneration: All UUIDs must be regenerated on import to avoid conflicts.
• Tenant isolation: Imported data must be scoped to the target tenant.
• Task numbers: task_number is scoped per team+chatID — must be re-sequenced on import.
• Auto-links: agent_links are auto-created when members are added — no need to export them.
• File size: Workspace files could be large — consider streaming or chunked upload for HTTP.
• Idempotency: Preview endpoint should be idempotent (no side effects).