← Documentation Home

Agent Studio - Development Guide

Setup, Testing, and Contribution Guidelines

Overview

This guide covers everything needed to set up a development environment, contribute to Agent Studio, run tests, and follow best practices for development across all platforms (macOS, iOS, iPadOS, Electron, VSCode, Web).

Prerequisites

Required Software

All Platforms: - Node.js: 20.15.0+ (LTS) - Use Volta or nvm for version management - npm: 10.7.0+ - Git: 2.40+ - Docker: 24+ (for local services) - Docker Compose: 2.20+

macOS Development: - Xcode: 15.0+ (for Swift/SwiftUI) - Xcode Command Line Tools: xcode-select --install - CocoaPods: 1.12+ (for iOS/iPadOS dependencies)

Optional: - Volta: For automatic Node.js version management - k9s: Kubernetes cluster management - Postman/Insomnia: API testing

System Requirements

Development Machine: - macOS: Sonoma 14.0+ (required for iOS/iPadOS development) - Memory: 16GB RAM minimum (32GB recommended) - Storage: 50GB free space - CPU: Apple Silicon (M1/M2/M3) or Intel Core i7+

Initial Setup

1. Clone Repository

# Clone from GitLab
git clone https://gitlab.bluefly.io/llm/common_npm/agent-studio.git
cd agent-studio

# Checkout development branch
git checkout development

2. Install Dependencies

# Install all workspace dependencies
npm install

# This installs dependencies for:
# - Root workspace
# - backend/
# - sdk/
# - apps/AgentStudio-electron
# - apps/AgentStudio-vscode
# - apps/AgentStudio-web

3. Configure Environment

# Copy environment template
cp .env.example .env

# Edit configuration
vim .env

Environment Variables:

# Backend API
AGENT_STUDIO_API_URL=http://localhost:3000
AGENT_STUDIO_WS_URL=ws://localhost:3000
AGENT_STUDIO_API_PORT=3000

# Agent Mesh
AGENT_MESH_URL=http://localhost:3005
AGENT_MESH_GRPC_PORT=50051

# NeuronLink AI (tokens stored in ~/.tokens/)
NEURONLINK_ANTHROPIC_API_KEY=~/.tokens/anthropic
NEURONLINK_OPENAI_API_KEY=~/.tokens/openai
NEURONLINK_MCP_ENABLED=true

# Database
DATABASE_URL=postgresql://agent_studio:password@localhost:5432/agent_studio
REDIS_URL=redis://localhost:6379
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Observability
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
JAEGER_ENDPOINT=http://localhost:14268/api/traces
PROMETHEUS_PORT=9090

# Sync
SYNC_INTERVAL=5000
SYNC_CONFLICT_STRATEGY=merge

# Development
NODE_ENV=development
LOG_LEVEL=debug

4. Start Local Services

Using Docker Compose:

# Start all dependencies
npm run docker:run

# Or manually with docker-compose
docker-compose up -d

# Services started:
# - PostgreSQL (5432)
# - Redis (6379)
# - Neo4j (7474, 7687)
# - Phoenix Arize (6006)
# - Jaeger (16686, 14268)
# - Prometheus (9090)
# - Grafana (3001)

Verify Services:

# Check service health
docker-compose ps

# View logs
docker-compose logs -f

# Access UIs
open http://localhost:6006    # Phoenix Arize
open http://localhost:16686   # Jaeger
open http://localhost:3001    # Grafana
open http://localhost:7474    # Neo4j Browser

5. Database Setup

# Run migrations (Prisma)
cd backend
npx prisma migrate dev

# Seed database (optional)
npx prisma db seed

# View database
npx prisma studio  # Opens at http://localhost:5555

6. OSSA Agent Setup

# Validate OSSA manifests
npm run ossa:validate

# Check agent registry
npm run buildkit:agents

# Deploy agents (if needed)
npm run ossa:deploy

Development Workflows

Backend Development

Start Backend Server:

# Development mode with hot reload
npm run dev:backend

# Or manually
cd backend
npm run dev

# Server starts at http://localhost:3000

Available Endpoints: - REST API: http://localhost:3000/api/v1 - GraphQL: http://localhost:3000/graphql (if enabled) - Metrics: http://localhost:3000/metrics - Health: http://localhost:3000/health - API Docs: http://localhost:3000/docs

Backend File Watching:

# TypeScript compilation in watch mode
npm run watch

# Run with nodemon for auto-restart
npm run dev:backend

macOS Desktop Development

Build and Run:

# Open Xcode project
open apps/AgentStudio-OSX/AgentStudio.xcodeproj

# Or build from command line
npm run build:macos

# Run
npm run start:macos

# Or use Swift Package Manager
cd apps/AgentStudio-OSX
swift build
swift run

SwiftUI Previews:

// Enable live previews in Xcode
import SwiftUI

struct EditorView_Previews: PreviewProvider {
    static var previews: some View {
        EditorView(document: .constant(Document.sample))
            .preferredColorScheme(.dark)
    }
}

Debug Shortcuts: - ⌘R: Build and run - ⌘.: Stop - ⌘B: Build only - ⌘⇧K: Clean build folder - ⌘⌥P: Resume SwiftUI preview

iOS/iPadOS Development

Setup iOS Environment:

# Install CocoaPods dependencies
npm run mobile:install-ios

# For iPad
npm run mobile:install-ipad

Run in Simulator:

# List available simulators
xcrun simctl list devices

# Run iOS app
npm run dev:ios

# Run iPad app
npm run dev:ipad

# Or open in Xcode
open apps/AgentStudio-iOS/AgentStudio-iOS.xcworkspace

Build for Device:

# Requires Apple Developer account and signing certificate
npm run build:ios

# Or build in Xcode (⌘B) with device selected

Debugging on Device: 1. Connect device via USB 2. Select device in Xcode 3. Build and run (⌘R) 4. Accept code signing prompt on device 5. View console logs in Xcode (⌘⇧C)

Electron Desktop Development

Start Electron IDE:

# Development mode (hot reload)
npm run dev:electron

# Or run specific commands
cd apps/AgentStudio-electron
npm run dev:renderer    # Start Vite dev server
npm run dev:electron    # Start Electron

# Production build
npm run package

Debug Electron:

# Enable DevTools
export ELECTRON_ENABLE_LOGGING=true
npm run dev:electron

# Open DevTools in app
# Cmd+Option+I (macOS)
# Ctrl+Shift+I (Windows/Linux)

Electron Main Process Debugging:

# Launch with inspector
electron --inspect=5858 .

# Connect Chrome DevTools
# Navigate to chrome://inspect

VSCode Extension Development

Launch Extension Host:

cd apps/AgentStudio-vscode

# Compile TypeScript
npm run build

# Or watch mode
npm run watch

Debug in VSCode:

  1. Open apps/AgentStudio-vscode in VS Code
  2. Press F5 (Run Extension)
  3. Extension Host window opens
  4. Test extension commands

Package Extension:

# Build VSIX package
cd apps/AgentStudio-vscode
npx vsce package

# Install locally
code --install-extension agent-studio-0.1.0.vsix

# Uninstall
code --uninstall-extension bluefly.agent-studio

Web Dashboard Development

Start Next.js Dev Server:

# Development mode
cd apps/AgentStudio-web
npm run dev

# Access at http://localhost:3002

Build for Production:

# Production build
npm run build

# Preview production build
npm run start

Testing

Unit Tests

Run All Tests:

# Run all unit tests
npm test

# Run tests for specific workspace
npm run test:sdk
npm run test:backend

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

Run Specific Tests:

# Backend tests
cd backend
npm test

# SDK tests
cd sdk
npm test

# Test single file
npx vitest run src/services/agent-registry.test.ts

Write Unit Tests (Vitest):

// agent-registry.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { AgentRegistryService } from './agent-registry.service';

describe('AgentRegistryService', () => {
  let service: AgentRegistryService;

  beforeEach(() => {
    service = new AgentRegistryService();
  });

  it('should register an agent', async () => {
    const manifest = { name: 'test-agent', version: '1.0.0' };
    const agent = await service.registerAgent(manifest);

    expect(agent.id).toBeDefined();
    expect(agent.manifest.name).toBe('test-agent');
  });

  it('should discover agents from directory', async () => {
    const agents = await service.discoverAgents();
    expect(agents.length).toBeGreaterThan(0);
  });
});

Integration Tests

Run Integration Tests:

# All integration tests
npm run test:integration

# Specific suite
npx playwright test tests/integration/api.spec.ts

Write Integration Tests (Playwright):

// api.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Agent API', () => {
  test('should list agents', async ({ request }) => {
    const response = await request.get('http://localhost:3000/api/v1/agents');

    expect(response.status()).toBe(200);
    const agents = await response.json();
    expect(Array.isArray(agents)).toBe(true);
  });

  test('should create agent task', async ({ request }) => {
    const response = await request.post(
      'http://localhost:3000/api/v1/agents/test-agent/tasks',
      {
        data: {
          type: 'code_generation',
          payload: { prompt: 'Create a function' }
        }
      }
    );

    expect(response.status()).toBe(201);
    const task = await response.json();
    expect(task.id).toBeDefined();
  });
});

End-to-End Tests

Run E2E Tests:

# All E2E tests
npm run test:e2e

# Headless mode
npx playwright test tests/e2e/

# Headed mode (watch browser)
npx playwright test tests/e2e/ --headed

# Debug mode
npx playwright test tests/e2e/ --debug

Write E2E Tests:

// workspace.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Workspace Management', () => {
  test('should create and open workspace', async ({ page }) => {
    await page.goto('http://localhost:3002');

    // Create workspace
    await page.click('text=New Workspace');
    await page.fill('[name="name"]', 'Test Workspace');
    await page.click('button:has-text("Create")');

    // Verify workspace opened
    await expect(page.locator('.workspace-name')).toHaveText('Test Workspace');
  });

  test('should sync file across devices', async ({ page, context }) => {
    // Open workspace
    await page.goto('http://localhost:3002/workspace/test');

    // Create file
    await page.click('text=New File');
    await page.fill('[name="filename"]', 'test.ts');
    await page.fill('.editor', 'console.log("test");');
    await page.keyboard.press('Control+S'); // Save

    // Simulate second device
    const page2 = await context.newPage();
    await page2.goto('http://localhost:3002/workspace/test');

    // Verify file synced
    await expect(page2.locator('.file-tree')).toContainText('test.ts');
  });
});

Mobile Tests (iOS/iPadOS)

XCTest Unit Tests:

// AgentServiceTests.swift
import XCTest
@testable import AgentStudio

final class AgentServiceTests: XCTestCase {
    var sut: AgentService!

    override func setUp() {
        super.setUp()
        sut = AgentService(apiClient: MockAPIClient())
    }

    func testFetchAgents() async throws {
        let agents = try await sut.fetchAgents()
        XCTAssertGreaterThan(agents.count, 0)
    }

    func testHealthCheck() async throws {
        let health = try await sut.healthCheck(agentId: "test-agent")
        XCTAssertEqual(health.status, .healthy)
    }
}

Run iOS Tests:

# Run all tests
xcodebuild test -scheme AgentStudio -destination 'platform=iOS Simulator,name=iPhone 15 Pro'

# Or in Xcode: Cmd+U

Code Quality

Linting

Run Linters:

# Lint all code
npm run lint

# Auto-fix issues
npm run lint:fix

# Lint specific workspace
npm run lint -w backend

ESLint Configuration:

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint", "prettier"],
  "rules": {
    "prettier/prettier": "error",
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn"
  }
}

Type Checking

Run TypeScript Compiler:

# Check all types
npm run typecheck

# Specific workspace
npm run typecheck:backend
npm run typecheck:sdk

# Watch mode
tsc --noEmit --watch

Code Formatting

Prettier:

# Format all files
npm run format

# Check formatting
npm run format:check

# Format specific files
npx prettier --write "backend/**/*.ts"

OSSA Validation

Validate Agent Manifests:

# Validate all agents
npm run ossa:validate

# Validate specific agent
ossa validate .agents/example-agent/manifest.json

# Check compliance level
ossa validate --compliance-level gold

Git Workflow

Branch Strategy

Main Branches: - main: Production-ready code - development: Integration branch for features - staging: Pre-production testing

Feature Branches:

# Create feature branch from development
git checkout development
git pull origin development
git checkout -b feature/agent-discovery

# Work on feature
git add .
git commit -m "feat: add agent discovery service"

# Push and create MR
git push origin feature/agent-discovery

Commit Messages

Conventional Commits:

type(scope): subject

body (optional)

footer (optional)

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting) - refactor: Code refactoring - test: Adding tests - chore: Maintenance tasks

Examples:

git commit -m "feat(agents): add OSSA 1.0 compliance validation"
git commit -m "fix(sync): resolve conflict detection race condition"
git commit -m "docs(wiki): update architecture diagrams"

Pre-Commit Hooks

Lefthook Configuration:

Agent Studio uses Lefthook for git hooks:

# lefthook.yml
pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    test:
      run: npm test
    ossa-validate:
      run: npm run ossa:validate

Install Hooks:

# Hooks are automatically installed with npm install
# Or manually
npx lefthook install

# Skip hooks (not recommended)
git commit --no-verify

Debugging

Backend Debugging

VS Code Launch Configuration:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Backend",
      "program": "${workspaceFolder}/backend/src/index.ts",
      "preLaunchTask": "tsc: build - backend/tsconfig.json",
      "outFiles": ["${workspaceFolder}/backend/dist/**/*.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

Attach to Running Process:

# Start with inspector
node --inspect dist/index.js

# Attach with Chrome DevTools
# Navigate to chrome://inspect

Frontend Debugging

React DevTools:

# Install React DevTools extension
# - Chrome: chrome://extensions
# - Firefox: about:addons

# Enable in Electron
npm run dev:electron
# DevTools automatically attached

Vue DevTools (if using Vue):

# Install browser extension
# Then enable in web dashboard

Performance Profiling

Node.js Profiling

# Generate CPU profile
node --prof dist/index.js

# Process profile
node --prof-process isolate-*.log > profile.txt

# Heap snapshot
node --inspect dist/index.js
# Open chrome://inspect
# Take heap snapshot

Lighthouse (Web)

# Install Lighthouse
npm install -g lighthouse

# Run audit
lighthouse http://localhost:3002 --view

# Generate report
lighthouse http://localhost:3002 --output html --output-path report.html

Documentation

Generate API Docs

# Generate TypeDoc documentation
npm run docs:build

# Serve locally
npm run docs:serve

# Access at http://localhost:8080

OpenAPI Documentation

# Sync OpenAPI specs
npm run openapi:sync

# Validate specs
npm run openapi:validate

# Bundle to JSON
npm run openapi:bundle

# Generate HTML docs
npm run openapi:docs

Contributing

Pull Request Process

  1. Create Feature Branch: bash git checkout -b feature/your-feature

  2. Make Changes:

  3. Follow coding standards
  4. Add tests

  5. Update documentation

  6. Run Quality Checks: bash npm run quality:check

  7. Commit Changes: bash git add . git commit -m "feat: your feature description"

  8. Push and Create MR: bash git push origin feature/your-feature # Create Merge Request in GitLab

  9. Code Review:

  10. Address reviewer comments
  11. Ensure CI passes

  12. Squash commits if needed

  13. Merge:

  14. Merge to development branch
  15. Delete feature branch

Code Review Guidelines

Reviewers Should Check: - [ ] Code follows project style guide - [ ] Tests are comprehensive and passing - [ ] Documentation is updated - [ ] No security vulnerabilities - [ ] Performance implications considered - [ ] OSSA compliance maintained - [ ] Breaking changes documented

Authors Should: - Keep PRs focused and small - Provide clear descriptions - Respond promptly to feedback - Ensure CI is green before requesting review

Troubleshooting

Common Issues

Port Already in Use:

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

Node Modules Issues:

# Clean install
rm -rf node_modules package-lock.json
npm install

Database Connection Errors:

# Restart Docker services
docker-compose restart postgres redis neo4j

# Check connectivity
psql -h localhost -U agent_studio -d agent_studio

TypeScript Compilation Errors:

# Clean build
npm run clean:all
npm run build

iOS Build Failures:

# Clean Xcode derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Update pods
cd apps/AgentStudio-iOS
pod install --repo-update

Sync Issues:

# Clear local sync cache
rm -rf ~/.agent-studio/sync-cache

# Force full sync
npm run workspace:backup
npm run workspace:restore

See Also: - Home - Back to wiki home - Features - Available features - Architecture - System architecture - Plugin Development - Extend Agent Studio

Last Updated: 2025-01-10 Maintainer: LLM Platform Team