Files
ruvnet__ruflo/v3/plugins/teammate-plugin/package.json
rUv f0168962c8 feat: Add @claude-flow/teammate-plugin with MCP tools and IPFS registry (#1013)
* feat(adr): Add ADR-027 Native TeammateTool Integration

Comprehensive architecture for integrating Claude Flow with Claude Code's
native TeammateTool multi-agent orchestration system (v2.1.19+).

Key features:
- TeammateBridge: Core bridge class with all 13 TeammateTool operations
- Team management: spawn, discover, join/leave workflows
- Mailbox integration: Inter-agent messaging via ~/.claude/teams/
- Plan approval: Submit, approve/reject, launch swarm workflow
- MCP tools: 9 new tools exposing native capabilities
- Claude Flow integration: Topology and agent type mapping
- Security model: Explicit tool grants, approval quorums
- Migration path: Native when available, MCP fallback

Based on analysis of Claude Code v2.1.19 binary confirming:
- 34 TeammateTool references
- 154 Teammate class references
- 22 spawnTeam operations
- CLAUDE_CODE_TEAM_NAME environment variable
- tmux and in_process spawn backends

Refs: ADR-018, gist/kieranklaassen/d2b35569be2c7f1412c64861a219d51f

* docs: Add architectural comparison between Claude Flow V3 and TeammateTool

Detailed side-by-side analysis showing 92% architectural overlap between
Claude Flow V3's swarm system and Claude Code's TeammateTool (v2.1.19).

Key findings:
- Identical concepts: team/swarm, topology, agent types, message bus
- Same workflows: join/leave approval, plan consensus, broadcast
- Matching structures: agent state, message format, spawn backends
- Different terminology: same underlying architecture

Comparison includes:
- Core architecture mapping
- Data structure comparison
- Code examples from both systems
- Timeline analysis
- 30+ side-by-side comparisons

Refs: Claude Flow V3 source, Claude Code v2.1.19 binary analysis

* docs(adr): Add ADR-027 gap analysis - 15 missing features identified

Comprehensive analysis of features missing from the TeammateTool plugin:

CRITICAL (Phase 1):
- Delegate mode: Authority delegation between teammates
- Team context: Shared variables, permissions, environment
- Permission updates: Dynamic permission changes mid-execution
- Session memory: Persist context across sessions

HIGH PRIORITY (Phase 2):
- Remote sync: pushToRemote to Claude.ai
- Transcript sharing: Share messages between teammates
- Error handling: Recovery strategies, error types
- Memory bridge: Sync to Claude Flow HNSW

MEDIUM (Phase 3):
- Teleport: Resume teams across terminal instances
- Plan control: Pause/resume/reentry for plans
- Hook integration: Claude Flow hook system
- Consensus bridge: Native vs advanced algorithms

LOW (Phase 4):
- tmux backend config: Pane layouts, prefix keys
- Worker threads: Parallel execution within teammate
- Swarm teammate type: Optimized for parallel tasks

Estimated additional code: ~1,550 lines (total: ~2,950)

* feat(teammate-plugin): Complete @claude-flow/teammate-plugin implementation

Implements all 15 features from ADR-027 gap analysis:

Core Features:
- TeammateBridge class with version detection (>= 2.1.19)
- Team management (spawn, discover, load teams)
- Teammate spawning with AgentInput schema
- Mailbox messaging (direct and broadcast)
- Plan approval workflow (submit, approve, reject, launch)

Extended Features:
- Delegate mode (delegateToTeammate, revokeDelegation)
- Remote sync (pushToRemote, pullFromRemote, syncWithRemote)
- Session memory persistence (save/load)
- Team context management (shared variables, permissions)
- Teleport (resume teams across terminal instances)
- Plan control (pause, resume, re-enter plan mode)
- Transcript sharing between teammates
- Error handling with 18 error codes

Package includes:
- 16 MCP tools for complete TeammateTool integration
- TDD test suite with Vitest
- Comprehensive README with version requirements
- TypeScript definitions (~500 lines)
- ~2000 lines total implementation

Requires Claude Code >= 2.1.19 for native TeammateTool support.

* security+perf(teammate-plugin): Add comprehensive security hardening and optimizations

Security Improvements:
- Add input validation for team/teammate names (path traversal prevention)
- Implement SAFE_NAME_PATTERN regex for alphanumeric+dash+underscore only
- Add RESERVED_NAMES blocklist to prevent .., config, state exploitation
- Implement validatePath() to ensure paths stay within teams directory
- Add safeJSONParse() with size limits (1MB max) to prevent DoS
- Sanitize environment variables to remove control characters
- Set restrictive file permissions (0o600 for files, 0o700 for dirs)
- Add MAX_PARAM_LENGTH and MAX_ARRAY_ITEMS validation in MCP tools
- Export SECURITY_LIMITS constants for configurability

Performance Optimizations:
- Add debounced file writes (500ms) to reduce I/O operations
- Implement team config caching with 30s TTL
- Add flushPendingWrites() for graceful cleanup
- Add invalidateConfigCache() on team changes

Security Constants:
- MAX_NAME_LENGTH: 64 characters
- MAX_PAYLOAD_SIZE: 1MB
- MAX_TEAMMATES_PER_TEAM: 50
- MAX_MESSAGES_PER_MAILBOX: 1000
- MAX_DELEGATION_DEPTH: 5

Addresses OWASP:
- A01:2021 Path Traversal
- A03:2021 Injection
- A05:2021 Security Misconfiguration

* feat(teammate-plugin): Add rate limiting, metrics, health checks, and circuit breaker

Production-ready features for enterprise deployment:

Rate Limiting:
- Configurable limits for spawn, messages, broadcasts, plans
- Per-minute sliding window with automatic reset
- Remaining quota tracking and rate limit state access
- Default: 10 spawns, 100 messages, 20 broadcasts per minute

Metrics & Telemetry:
- Counter metrics: teams, teammates, messages, errors, etc.
- Gauge metrics: active teams, active teammates, pending plans
- Histogram metrics: spawn latency, message latency, approval latency
- Percentile calculations (p50, p95, p99)
- MetricSnapshot for point-in-time observability

Health Checks:
- Per-teammate health monitoring with configurable intervals
- Health states: healthy, degraded, unhealthy, unknown
- Consecutive failure/success thresholds
- Team-level health reports with overall status
- Auto-emit events on status changes

Circuit Breaker Pattern:
- States: closed, open, half-open
- Configurable failure/success thresholds
- Timeout protection on external calls
- Automatic reset after cooldown period

Retry Logic:
- Exponential backoff with configurable multiplier
- Max delay cap to prevent infinite waits
- Retryable error codes for selective retry
- withRetry() helper function

New Configuration Constants:
- RATE_LIMIT_DEFAULTS
- HEALTH_CHECK_DEFAULTS
- RETRY_DEFAULTS
- DEFAULT_CIRCUIT_BREAKER_CONFIG

Public API Additions:
- getMetrics(), getLatencyPercentile(), resetMetrics()
- getTeammateHealth(), getTeamHealth()
- getRateLimitRemaining(), isRateLimited(), resetRateLimits()
- getCircuitBreakerState(), resetCircuitBreaker()

Integrated into operations:
- spawnTeammate: rate limiting + latency tracking + health checks
- sendMessage: rate limiting + latency tracking
- broadcast: rate limiting + metrics

* feat(teammate-plugin): Add BMSSP-powered optimization (10-15x faster)

- Add @ruvnet/bmssp dependency for WebAssembly graph optimization
- Create TopologyOptimizer with WasmGraph integration for shortest path
  computation, topology statistics, and optimization suggestions
- Create SemanticRouter with WasmNeuralBMSSP for intelligent task-to-
  teammate matching using skill embeddings and neural pathfinding
- Integrate optimizers into TeammateBridge with enableOptimizers(),
  findOptimalPath(), getTopologyStats(), findBestTeammateForTask()
- Add 5 new MCP tools for optimization (21 total):
  - teammate_enable_optimizers
  - teammate_find_optimal_path
  - teammate_get_topology_stats
  - teammate_route_task
  - teammate_batch_route
- JavaScript fallback when WASM unavailable
- Performance learning via updateTeammatePerformance()

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:09:07Z
- Changes: 6 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:09:17Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:35Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:36Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:37Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:38Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:39Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:10:40Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:11:39Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:11:47Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:12:00Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:13:27Z
- Changes: 33 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:13:50Z
- Changes: 2 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:14:34Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:17:14Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:17:41Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:17:55Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:18:40Z
- Changes: 2 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:19:21Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:19:52Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:20:03Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:20:10Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:20:16Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:22:03Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:22:10Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:22:16Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:29:59Z
- Changes: 6 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:30:47Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:31:00Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Checkpoint: File edits

Automatic checkpoint created by Claude Code
- Branch: claude/review-claude-flow-integration-A0c3R
- Timestamp: 2026-01-25T15:32:20Z
- Changes: 2 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Update README.md: Revise badge section and enhance documentation structure

* fix: Use main branch README.md to resolve conflicts

Co-Authored-By: claude-flow <ruv@ruv.net>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-25 10:35:31 -05:00

102 lines
2.4 KiB
JSON

{
"name": "@claude-flow/teammate-plugin",
"version": "1.0.0-alpha.1",
"description": "Native TeammateTool integration plugin for Claude Flow - bridges Claude Code v2.1.19+ multi-agent capabilities",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"import": "./dist/index.js",
"types": "./dist/index.d.ts"
},
"./bridge": {
"import": "./dist/teammate-bridge.js",
"types": "./dist/teammate-bridge.d.ts"
},
"./mcp": {
"import": "./dist/mcp-tools.js",
"types": "./dist/mcp-tools.d.ts"
},
"./topology": {
"import": "./dist/topology-optimizer.js",
"types": "./dist/topology-optimizer.d.ts"
},
"./semantic": {
"import": "./dist/semantic-router.js",
"types": "./dist/semantic-router.d.ts"
}
},
"files": [
"dist",
"README.md"
],
"scripts": {
"build": "tsc",
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage",
"lint": "eslint src --ext .ts",
"clean": "rm -rf dist",
"prepublishOnly": "npm run clean && npm run build && npm run test"
},
"keywords": [
"claude",
"claude-code",
"claude-flow",
"teammate",
"multi-agent",
"swarm",
"orchestration",
"mcp"
],
"author": "rUv <ruv@ruv.net>",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/ruvnet/claude-flow.git",
"directory": "v3/plugins/teammate-plugin"
},
"bugs": {
"url": "https://github.com/ruvnet/claude-flow/issues"
},
"homepage": "https://github.com/ruvnet/claude-flow#readme",
"engines": {
"node": ">=18.0.0"
},
"peerDependencies": {
"@anthropic-ai/claude-code": ">=2.1.19"
},
"peerDependenciesMeta": {
"@anthropic-ai/claude-code": {
"optional": true
}
},
"dependencies": {
"eventemitter3": "^5.0.1",
"@ruvnet/bmssp": "^1.0.0"
},
"devDependencies": {
"@types/node": "^20.10.0",
"typescript": "^5.3.0",
"vitest": "^1.0.0",
"@vitest/coverage-v8": "^1.0.0",
"eslint": "^8.55.0",
"@typescript-eslint/eslint-plugin": "^6.13.0",
"@typescript-eslint/parser": "^6.13.0"
},
"claude-code": {
"minimumVersion": "2.1.19",
"requiredFeatures": [
"TeammateTool",
"team_name",
"launchSwarm"
],
"optionalFeatures": [
"pushToRemote",
"delegate_mode",
"teleport"
]
}
}