feat: SDK version tracking with upgrade prompts

Persist heartbeat metadata (sdk_version) via Store.UpdateMetadata, add
GitHub-based version check service polling latest CLI release, expose
sdk_version in provider/admin API responses, and display version badges
with upgrade prompt modals in the dashboard (8-locale i18n).

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

Author: gcmsg

cmd/peerclawd/main.go

@@ -33,6 +33,7 @@ import (
 	"github.com/peerclaw/peerclaw-server/internal/review"
 	"github.com/peerclaw/peerclaw-server/internal/useracl"
 	"github.com/peerclaw/peerclaw-server/internal/userauth"
+	"github.com/peerclaw/peerclaw-server/internal/versioncheck"
 	"github.com/peerclaw/peerclaw-server/internal/verification"
 	goredis "github.com/redis/go-redis/v9"
 )
@@ -395,6 +396,18 @@ func main() {
 			sigHub.SetBroker(signaling.NewLocalBroker(sigHub))
 		}
 	}
+	// Initialize version check service.
+	if cfg.VersionCheck.Enabled {
+		vcInterval, err := time.ParseDuration(cfg.VersionCheck.Interval)
+		if err != nil {
+			vcInterval = time.Hour
+		}
+		vcService := versioncheck.New(cfg.VersionCheck.Repo, vcInterval, logger)
+		httpServer.SetVersionCheck(vcService)
+		go vcService.Start(ctx)
+		logger.Info("version check service started", "repo", cfg.VersionCheck.Repo, "interval", vcInterval)
+	}
+
 	// Register routes after all services are configured so that
 	// optional-service routes (claim tokens, contacts, etc.) are included.
 	httpServer.RegisterRoutes()

internal/config/config.go

@@ -24,6 +24,7 @@ type Config struct {
 	UserAuth      UserAuthConfig      `yaml:"user_auth"`
 	SMTP          SMTPConfig          `yaml:"smtp"`
 	Retention     RetentionConfig     `yaml:"retention"`
+	VersionCheck  VersionCheckConfig  `yaml:"version_check"`
 }
 
 // SMTPConfig holds SMTP email settings.
@@ -45,6 +46,13 @@ type RetentionConfig struct {
 	CleanupInterval      string `yaml:"cleanup_interval"`
 }
 
+// VersionCheckConfig holds SDK version check settings.
+type VersionCheckConfig struct {
+	Enabled  bool   `yaml:"enabled"`  // default true
+	Repo     string `yaml:"repo"`     // default "peerclaw/peerclaw-cli"
+	Interval string `yaml:"interval"` // default "1h"
+}
+
 // AuthConfig holds authentication settings.
 type AuthConfig struct {
 	Required bool `yaml:"required"` // When true, reject unauthenticated requests. Default true.
@@ -206,6 +214,11 @@ func DefaultConfig() *Config {
 			RefreshTTL: "168h",
 			BcryptCost: 12,
 		},
+		VersionCheck: VersionCheckConfig{
+			Enabled:  true,
+			Repo:     "peerclaw/peerclaw-cli",
+			Interval: "1h",
+		},
 		Retention: RetentionConfig{
 			Enabled:              true,
 			ReputationEventsDays: 90,

internal/registry/postgres.go

@@ -255,6 +255,25 @@ func (s *PostgresStore) UpdateHeartbeat(ctx context.Context, id string, status a
 	return nil
 }
 
+func (s *PostgresStore) UpdateMetadata(ctx context.Context, id string, metadata map[string]string) error {
+	if len(metadata) == 0 {
+		return nil
+	}
+	patch, _ := json.Marshal(metadata)
+	res, err := s.db.ExecContext(ctx,
+		"UPDATE agents SET metadata = COALESCE(metadata::jsonb, '{}'::jsonb) || $1::jsonb WHERE id = $2",
+		string(patch), id,
+	)
+	if err != nil {
+		return err
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("agent %s not found", id)
+	}
+	return nil
+}
+
 func (s *PostgresStore) FindByCapabilities(ctx context.Context, capabilities []string, proto string, maxResults int) ([]*agentcard.Card, error) {
 	var conditions []string
 	var args []any

internal/registry/service.go

@@ -108,14 +108,23 @@ func (s *Service) Deregister(ctx context.Context, agentID string) error {
 	return nil
 }
 
-// Heartbeat updates the agent's heartbeat timestamp.
-func (s *Service) Heartbeat(ctx context.Context, agentID string, status agentcard.AgentStatus) (time.Time, error) {
+// Heartbeat updates the agent's heartbeat timestamp and optionally merges metadata.
+func (s *Service) Heartbeat(ctx context.Context, agentID string, status agentcard.AgentStatus, metadata map[string]string) (time.Time, error) {
 	if status == "" {
 		status = agentcard.StatusOnline
 	}
 	if err := s.store.UpdateHeartbeat(ctx, agentID, status); err != nil {
 		return time.Time{}, fmt.Errorf("heartbeat: %w", err)
 	}
+
+	// Merge metadata if provided, but prevent overwriting ownership.
+	if len(metadata) > 0 {
+		delete(metadata, "owner_user_id")
+		if err := s.store.UpdateMetadata(ctx, agentID, metadata); err != nil {
+			s.logger.Warn("failed to update heartbeat metadata", "agent_id", agentID, "error", err)
+		}
+	}
+
 	// Next heartbeat expected within the configured interval.
 	interval := s.HeartbeatInterval
 	if interval <= 0 {

internal/registry/service_test.go

@@ -91,7 +91,7 @@ func TestService_Heartbeat(t *testing.T) {
 		Protocols: []protocol.Protocol{protocol.ProtocolA2A},
 	})
 
-	deadline, err := svc.Heartbeat(ctx, card.ID, agentcard.StatusOnline)
+	deadline, err := svc.Heartbeat(ctx, card.ID, agentcard.StatusOnline, nil)
 	if err != nil {
 		t.Fatalf("Heartbeat: %v", err)
 	}

internal/registry/sqlite.go

@@ -281,6 +281,26 @@ func (s *SQLiteStore) UpdateHeartbeat(ctx context.Context, id string, status age
 	return nil
 }
 
+func (s *SQLiteStore) UpdateMetadata(ctx context.Context, id string, metadata map[string]string) error {
+	if len(metadata) == 0 {
+		return nil
+	}
+	// Read existing metadata, merge, write back.
+	var existing string
+	err := s.db.QueryRowContext(ctx, "SELECT COALESCE(metadata, '{}') FROM agents WHERE id = ?", id).Scan(&existing)
+	if err != nil {
+		return fmt.Errorf("agent %s not found", id)
+	}
+	merged := map[string]string{}
+	_ = json.Unmarshal([]byte(existing), &merged)
+	for k, v := range metadata {
+		merged[k] = v
+	}
+	data, _ := json.Marshal(merged)
+	_, err = s.db.ExecContext(ctx, "UPDATE agents SET metadata = ? WHERE id = ?", string(data), id)
+	return err
+}
+
 func (s *SQLiteStore) FindByCapabilities(ctx context.Context, capabilities []string, proto string, maxResults int) ([]*agentcard.Card, error) {
 	var conditions []string
 	var args []any

internal/registry/store.go

@@ -55,6 +55,9 @@ type Store interface {
 	// UpdateHeartbeat updates the heartbeat timestamp and status of an agent.
 	UpdateHeartbeat(ctx context.Context, id string, status agentcard.AgentStatus) error
 
+	// UpdateMetadata merges the provided metadata keys into the agent's existing metadata.
+	UpdateMetadata(ctx context.Context, id string, metadata map[string]string) error
+
 	// FindByCapabilities returns agents that match any of the given capabilities.
 	FindByCapabilities(ctx context.Context, capabilities []string, protocol string, maxResults int) ([]*agentcard.Card, error)
 

internal/server/admin_handler.go

@@ -555,6 +555,22 @@ func (s *HTTPServer) registerAdminRoutes() {
 
 	// Invocation log.
 	s.mux.Handle("GET /api/v1/admin/invocations", wrapAdmin(s.handleAdminListInvocations))
+
+	// SDK version check.
+	s.mux.Handle("GET /api/v1/admin/sdk-version", wrapAdmin(s.handleAdminSDKVersion))
+}
+
+// handleAdminSDKVersion handles GET /api/v1/admin/sdk-version.
+func (s *HTTPServer) handleAdminSDKVersion(w http.ResponseWriter, r *http.Request) {
+	if s.versionCheck == nil {
+		s.jsonError(w, "version check not enabled", http.StatusNotImplemented)
+		return
+	}
+	latest, releaseURL := s.versionCheck.Latest()
+	s.jsonResponse(w, http.StatusOK, map[string]any{
+		"latest":      latest,
+		"release_url": releaseURL,
+	})
 }
 
 // queryInt extracts an integer query parameter with a default value.

internal/server/http.go

@@ -26,6 +26,7 @@ import (
 	"github.com/peerclaw/peerclaw-server/internal/invocation"
 	"github.com/peerclaw/peerclaw-server/internal/review"
 	"github.com/peerclaw/peerclaw-server/internal/userauth"
+	"github.com/peerclaw/peerclaw-server/internal/versioncheck"
 	"github.com/peerclaw/peerclaw-server/internal/verification"
 	"go.opentelemetry.io/otel/trace"
 )
@@ -69,6 +70,7 @@ type HTTPServer struct {
 	a2aTasks               *a2aBridgeTasks
 	acpRuns                *acpBridgeRuns
 	mcpSessions            *mcpBridgeSessions
+	versionCheck           *versioncheck.Service
 	cleanupCancel          context.CancelFunc // cancels bridge cleanup goroutines
 }
 
@@ -202,6 +204,11 @@ func (s *HTTPServer) SetBridgeRateLimiter(rl *IPRateLimiter) {
 	s.bridgeRateLimiter = rl
 }
 
+// SetVersionCheck sets the version check service for SDK upgrade prompts.
+func (s *HTTPServer) SetVersionCheck(vc *versioncheck.Service) {
+	s.versionCheck = vc
+}
+
 // UserACLChecker checks whether a user has access to an agent.
 type UserACLChecker interface {
 	IsAllowed(ctx context.Context, agentID, userID string) (bool, error)
@@ -565,7 +572,7 @@ func (s *HTTPServer) handleHeartbeat(w http.ResponseWriter, r *http.Request) {
 		status = agentcard.StatusOnline
 	}
 
-	deadline, err := s.registry.Heartbeat(r.Context(), id, status)
+	deadline, err := s.registry.Heartbeat(r.Context(), id, status, req.Metadata)
 	if err != nil {
 		s.jsonError(w, err.Error(), http.StatusNotFound)
 		return
@@ -752,6 +759,7 @@ func (s *HTTPServer) registerProviderRoutes() {
 	s.mux.Handle("GET /api/v1/provider/agents/{id}/analytics", s.wrapUserAuth(s.handleProviderAgentAnalytics))
 	s.mux.Handle("GET /api/v1/provider/dashboard", s.wrapUserAuth(s.handleProviderDashboard))
 	s.mux.Handle("GET /api/v1/provider/directory", s.wrapUserAuth(s.handleConsoleDirectory))
+	s.mux.Handle("GET /api/v1/provider/sdk-version", s.wrapUserAuth(s.handleProviderSDKVersion))
 }
 
 func (s *HTTPServer) registerClaimTokenRoutes() {

internal/server/provider_handler.go

@@ -188,6 +188,13 @@ func (s *HTTPServer) handleProviderGetAgent(w http.ResponseWriter, r *http.Reque
 		resp["visibility"] = flags.Visibility
 	}
 
+	// Expose sdk_version from metadata.
+	if card.Metadata != nil {
+		if v, ok := card.Metadata["sdk_version"]; ok {
+			resp["sdk_version"] = v
+		}
+	}
+
 	// Enrich with live reputation score and verified status.
 	if s.reputation != nil {
 		score, _ := s.reputation.GetScore(r.Context(), card.ID)
@@ -498,6 +505,19 @@ func (s *HTTPServer) handleProviderDashboard(w http.ResponseWriter, r *http.Requ
 	})
 }
 
+// handleProviderSDKVersion handles GET /api/v1/provider/sdk-version.
+func (s *HTTPServer) handleProviderSDKVersion(w http.ResponseWriter, r *http.Request) {
+	if s.versionCheck == nil {
+		s.jsonError(w, "version check not enabled", http.StatusNotImplemented)
+		return
+	}
+	latest, releaseURL := s.versionCheck.Latest()
+	s.jsonResponse(w, http.StatusOK, map[string]any{
+		"latest":      latest,
+		"release_url": releaseURL,
+	})
+}
+
 // handleConsoleDirectory handles GET /api/v1/provider/directory — console directory search.
 // Unlike the public directory, this includes the user's own private agents.
 func (s *HTTPServer) handleConsoleDirectory(w http.ResponseWriter, r *http.Request) {